Repo readiness review

Repo Readiness Review

Use this skill to turn an uncertain repository state into a concise, evidence-backed readiness report and, when appropriate, make small fixes that unblock verification.

Scope

Cover the repository surfaces that determine whether work is understandable and shippable:

• Git state: branch, remotes, staged changes, unstaged changes, untracked files, ignored artifacts, conflicts, recent commits, and target branch or commit.
• Base synchronization: whether the branch is ahead, behind, diverged, freshly pulled, or blocked by conflicts with the core branch.
• Change intent: what changed, why it appears to exist, whether files should be tracked, and whether deleted files break entry points.
• Hosted context: GitHub or other forge branch/PR/issues/checks when available and relevant.
• Deployment readiness: CI workflows, deploy workflows, release config, environment variable names, secret or variable references, docs, and generated config.
• Verification: focused build, test, lint, typecheck, smoke, or syntax checks that match the risk.

Workflow

1. Identify the repository root, current branch, remotes, upstream branch, and requested target.
2. Inspect local state before editing:

git status --short --branch --ignored
git diff --stat
git diff --name-status
git diff --cached --stat
git ls-files --others --exclude-standard

3. Determine the core branch to reconcile against. Prefer the user's target; otherwise use the configured upstream, remote default branch, or common branch names in this order: main, master, trunk, develop.
4. Fetch remote refs and compare:

git fetch --all --prune
git branch --show-current
git rev-parse --abbrev-ref --symbolic-full-name @{u}
git status --short --branch

5. Pull, merge, or rebase the core branch when the user asks for readiness against current base. Choose the repo's established strategy when visible; otherwise prefer merge or fast-forward over rebase when local user work is dirty. If the worktree is dirty, use an explicit preservation strategy such as git pull --no-rebase --autostash <remote> <branch> or create a named stash before merging. Report the exact command and any stash left behind.
6. Check for unmerged paths and conflict markers after the pull/merge. Resolve only when the correct side is clear from current code, tests, docs, or API contracts; otherwise report the conflict and the exact decision needed.
7. Read repo instructions and entry points: AGENTS.md, README*, CONTRIBUTING*, package manifests, CI workflows, deploy config, docs, and scripts related to changed paths.
8. Classify local work:
   • Track source, tests, docs, workflows, lockfiles, migrations, public assets, fixtures, and intentional generated artifacts.
   • Ignore or leave local-only dependencies, build output, caches, logs, editor files, .env files, local credentials, and machine-specific config.
   • Treat staged changes separately from unstaged changes; do not assume staged work belongs to the current task.
9. Verify changed or deleted entry points. If a script, workflow, package command, doc link, or import points to a missing file, either restore the file or update the reference when the intended cleanup is clear.
10. For GitHub or deployment readiness, compare code references with hosted settings when tools/permissions allow:

• Repository variables and secrets referenced by workflows.
• Required workflow files and branch/PR checks.
• Environment names, deploy targets, release settings, and documented setup values.
• If permission is missing, say exactly which check could not be completed.

11. Make narrow fixes when the request asks to clean or prepare the repo and the fix is low risk. Examples: remove conflict markers, restore a referenced deleted script, add a missing workflow env var, update docs for a new config value, or add focused tests around a changed behavior.
12. Run focused verification. Prefer the smallest commands that cover the edited surface, then broaden only when the blast radius justifies it.

Guardrails

• Do not stage, unstage, commit, push, delete, or rewrite user work unless the user asked for that class of action or it is necessary to mark a resolved conflict; explain it when you do.
• Never revert unrelated changes. Work with local changes that affect the task, and ignore unrelated local files.
• Do not drop autostashes or manual stashes created during reconciliation unless the user explicitly asks or the stash is proven redundant and the user approves.
• Do not expose secret values in the final report. It is acceptable to report that a variable or secret exists by name and timestamp when the tooling returns that metadata.
• Do not add broad .gitignore patterns to hide real source files.
• Prefer primary evidence from files, command output, CI config, and hosted settings over inference.

Useful Hosted Checks

Use the available forge tools or CLI when relevant:

gh auth status
gh workflow list --all
gh variable list --json name,updatedAt
gh secret list --json name,updatedAt
gh pr status
gh run list --limit 10

Adapt for GitLab, Bitbucket, or another forge by checking equivalent CI variables, protected branch settings, merge request state, and pipeline status.

Output

Lead with the readiness state, then the evidence:

• Ready: no known blockers; list verification run and any residual risks.
• Ready after specific follow-up: low-risk external setup remains, such as adding a missing repository variable.
• Not ready: blockers such as unresolved conflicts, failing verification, missing required secrets, broken entry points, or ambiguous staged work.

Include:

• Current branch/target and whether local work is staged, unstaged, or untracked.
• Core branch sync result: branch pulled or merged, commits incorporated, conflicts encountered, conflict resolutions made, and any stash that remains.
• Fixes made, with file references.
• Items that should be tracked, ignored, restored, deleted, or left local-only.
• GitHub/CI/deployment readiness findings.
• Verification commands and results.
• Remaining decisions or risks, ordered by severity.