Repo Readiness

Repo Readiness

Apply task scope and authorization when using this workflow; it defines how existing approval and task boundaries apply.

Use this skill to answer whether a change, branch, PR, or workstream is ready. It is an orchestrator: follow repo-specific instructions first, then call the relevant focused skills or tools instead of duplicating their details.

When the user asks whether work is done, ready to hand off, or safe to exit, use this skill first for gates and evidence, then use work-closeout for final hygiene, artifact cleanup, and durable parking state. Do not force a single skill when both readiness and closeout are required. A safe-to-exit, wrap-up, pause, or handoff prompt must not end with a readiness-only final answer; the final answer must come from work-closeout and include both Love Gate and Safe to exit.

Outcome

Return a truthful verdict—ready, not ready, partially ready, or blocked—with the required gates, passed/failed/pending/not-run evidence, blockers, and the smallest next action that would change the verdict. Readiness is complete only when the evidence covers the changed surface and any configured code, docs, inspection, browser, CI, deployment, or security gates.

Workflow

1. Identify the repo, branch, active task, changed files, and whether a PR/issue is in play.

2. Check .github/github.json before inferring gates. If it has a qualityGate block, use it for how to run tests, lint/static analysis, format checks, typechecks, builds, and IDE/static inspections. Use qualityGate.docsRequiredWhen for docs freshness triggers. If it has a docs block, prefer docs.index and relevant docs.* paths as the docs entry points. Fall back to repo instructions (AGENTS.md, README, docs/policies/gates), CI files, and manifests for any unset metadata fields. If a durable command is confidently inferred, cite the source and propose a metadata addition rather than auto-writing it.

3. Inspect local state:

   git status --short --branch
   

4. For code changes, delegate inspection execution and triage to jetbrains-inspection and follow the authoritative section below. When .github/github.json defines qualityGate.inspection, readiness must include JetBrains evidence or an explicit not-run reason. For blank, missing, contradictory, or surprising config, use a safe one-off changed_files default only when the helper can infer the route, and ask the user before changing repo policy.

   If qualityGate.inspection.prepare is configured, run that exact command in the target linked worktree before the first JetBrains assessment. The command may create ignored local .venv/ or .idea/ state, but a nonzero exit or any tracked-file mutation is a preparation blocker. Do not invent or substitute a replacement setup command.

   If the shared Launchplane context helper is present and configured, call it once as optional readiness context for the active repo/branch/PR:

   uv run <skill-dir>/../launchplane/scripts/launchplane-context.py --repo OWNER/REPO
   

   Use available context only as a hint for product mapping, preview readiness, Every Code state, deploy evidence, or source-of-truth links. Treat no_context, unavailable, unauthorized, invalid, or helper failure as normal absence and continue with local/GitHub readiness checks. Do not print raw helper stderr or copy helper payloads into readiness output.

   If you inspect worktrees, ignore Codex Desktop or Every Code auto-review worktrees under ~/.code/working/<repo>/branches/auto-review* unless the user's task is specifically about that review. They are detached external review context and should not affect readiness for the active repo/branch.

   When background auto-review results or ledgers are available in session context or repo tooling, follow ../references/background-review-reporting.md. Match the observation to the active branch, PR, and head SHA before using it as evidence. Do not declare a branch, PR, release, or handoff green while blocking findings against the current target are unresolved or while a matching review is in flight. When no lifecycle evidence is visible before a possible post-turn trigger, report not yet observable; do not infer a skipped or not-emitted outcome, and do not delay the final response solely waiting for that trigger. If a matching review is already in flight, use only bounded waiting when useful; otherwise preserve it as pending evidence in the readiness handoff. If a finding points at a detached auto-review* worktree or older snapshot, verify it against current HEAD before treating it as blocking. Detached auto-review worktrees are not dirty active state; only matching review findings and lifecycle evidence matter.

5. Apply Gate Selection for the required breadth at this stage, including the final-readiness defaults for lint/static analysis and IDE inspection. Run the required repo gates and the narrowest additional checks that cover the change and risk. Before saying code is ready, confirm current evidence covers the required scope. Broaden for missing coverage, changed behavior, failures, unresolved concerns, or an explicit repo requirement; do not rerun passing checks that cover the required scope for an unchanged revision and environment merely for closeout.

6. If GitHub state matters, use github for PR checks, Actions, review status, labels, deploy health, and mergeability. Use github-plan for planning issue indexes, Project state, blocker graphs, and planning GraphQL operations. Use the GitHub skills' structured command-policy metadata as the helper catalog; this skill decides what evidence is needed, not which raw gh command to run. If an open PR still needs repeated CI/review/mergeability polling after a branch update, check rerun, rebase, review-fix push, or "safe to exit" check, route that follow-through to babysit-pr; keep this skill focused on the point-in-time readiness verdict and evidence. For stacked PRs, include whether a rollup/integration PR would be safer or faster than merging each layer and rerunning expensive checks repeatedly, unless repo metadata or task context says Launchplane owns the merge train. For Launchplane-managed trains, verify or route through launchplane instead of recommending a hand-built GitHub rollup.

7. If UI was touched, use browser-ui-review for browser-visible validation.

8. If security is in scope, use security-review explicitly; do not silently turn normal readiness into a full security audit.

9. Report readiness concisely. If the user asked for handoff, wrap-up, or safe-to-exit, treat any readiness report as interim evidence and continue into work-closeout after the readiness answer is established. The closeout answer owns the final safe-to-exit verdict and must include Love Gate.

Readiness To Closeout Handoff

When work-closeout will run after this skill, make the readiness answer easy to consume instead of asking closeout to rediscover gate state. Include these fields in chat, a PR comment, or the owning issue when durable state is needed:

• Status: ready, not ready, partially ready, or blocked.
• Required gates: the checks inferred from .github/github.json, repo docs, CI, and the changed surface.
• Passed, failed, pending, and not-run evidence with concrete reasons.
• For PR readiness, preserve watcher/check evidence, pending counts, and unsettled long checks explicitly; do not flatten an unsettled PR into a one-shot "mergeable" or "ready" summary.
• For release, runtime, deploy, or browser/device-specific blockers, name the exact environment checked. If only a substitute was available, name the substitute and keep the gap visible in the readiness status.
• Metadata/docs impact: whether .github/github.json or docs changed, were checked, are stale, or were intentionally not updated.
• Background review: the target-matched point-in-time state, observation time or head SHA, and the canonical state: not yet observable, in flight, observation unavailable, or an exact terminal outcome.
• Next action: the smallest step that would change readiness.

This handoff is evidence for work-closeout; it is not cleanup. Do not delete artifacts, remove worktrees, close planning issues, or claim safe-to-exit from this skill alone. If the user asked whether they can exit or stop, the final response belongs to work-closeout, not this readiness handoff.

Both this skill and work-closeout read .github/github.json with the same schema expectations: qualityGate, docs, metadataFreshness, cleanup, importantWorkflows, repo relationships, health signals, and ownership or Launchplane routing when present. Readiness uses those fields to decide what must be verified; closeout uses the same fields to decide what final evidence, metadata updates, and cleanup remain.

Use ../references/every-code-formatting.md for readiness reports and durable readiness comments: lead with status, cite concrete evidence, and keep skipped or pending checks explicit without copying large logs. Use ../references/background-review-reporting.md for Background Review state.

Gate Selection

• Docs-only: validate links/rendering when practical; do not run full code gates unless docs describe executable behavior. Prefer docs.index when repo metadata provides it.
• Narrow code change: run targeted tests/checks for touched behavior.
• Shared contract, deployment, release, or security-sensitive change: run the broader repo gate and any required inspection/security checks.
• Shared agent instructions, approval or safety rules, or a destructive helper: nothing executable catches a mistake here, so also get a review by another model and weigh it under ../references/model-review.md.
• Frontend/UI change: run browser validation in addition to build/type/test checks required by the repo.
• Docker image change: prefer real image build/smoke/inspection over static Dockerfile review when downstream behavior changes.

Quality default: all code changes should trend toward zero known lint/static analysis and IDE inspection noise. Run narrow gates while iterating, but before declaring a code change ready, safe to merge, safe to ship, or ready to hand off, run broad practical gates when tooling exists: normally whole-repo lint/static analysis and whole-project IDE inspection. Use downstream/related repo gates when contracts, shared packages, deployment behavior, or cross-repo ownership changes.

If a broad gate is too slow, unavailable, blocked by IDE indexing/tooling, likely destructive, or disproportionate for a docs-only change, report it as not run with the reason. Ask before running gates that mutate shared environments or external resources. If linting a file for the first time, dry-run first when the environment supports it.

For code-change readiness, inspection evidence is one of: a clean jetbrains-inspection closeout result with scope and route, actionable findings that were fixed or tracked, or a concrete not-run reason such as unavailable IDE, blocked indexing, docs-only scope, or user-approved parking. Missing inspection evidence for a configured code gate means the readiness answer is not fully ready.

Existing lint/inspection noise is not an invisible background condition. Fix real findings the right way when straightforward or in the affected area. If findings are broad but real, call them out and decide whether to include a cleanup pass or track a focused cleanup item. If a finding is a false positive or cannot be fixed cleanly, discuss an explicit suppression, baseline, or config change.

Reviewability is part of readiness. Unless a change is mostly mechanical, treat diffs over roughly 800 changed lines as a review-risk signal; for complex logic changes, prefer stages under roughly 500 changed lines. If a change is larger, explain whether it can be split into reviewable stages and identify the smallest coherent stage to land first, based on the actual diff, dependencies, and affected call sites.

When work changes docs routing, validation commands, lint/inspection routing, required docs conditions, important workflows, health endpoints, repo relationships, cleanup policy, or ownership boundaries, check whether .github/github.json is stale. Do not treat manifest-owned dependency or inventory changes as a reason to copy those facts into workflow metadata; point to the canonical manifests or docs instead. Report metadata drift as a readiness warning or blocker only when it changes what "ready" means for the current task.

For every non-trivial code change, perform a docs-impact check. If docs-required triggers match, inspect the relevant docs and update them when stale. If no docs update is needed, say why briefly in readiness output.

JetBrains IDE And Inspections

Delegate JetBrains/PyCharm/IntelliJ/WebStorm inspection execution and triage to jetbrains-inspection. Treat stale results, incomplete capture, indexing, session drift, unavailable IDE, ambiguous routing, or wrong-worktree routing as not-clean states. Do not add suppressions, disable inspections, or change IDE inspection profiles without explicit approval unless the repo already has an approved convention.

If the repo inspection config is blank or feels wrong, ask the user when the choice affects durable repo policy or readiness. Examples: configured IDE does not match the open project, configured scope is disproportionate to the change, or configured paths point away from the active worktree. For a one-off local check with no durable policy change, prefer the helper's safe inferred route and changed_files scope, and report that assumption.

When tracked IDE configuration changes, apply ../references/ide-configuration-policy.md. An unresolved tracked IDE diff is not clean: review its exact hunks, ignore rules, repository policy, and history, then preserve the canonical shared form plus only safe hunks. Do not call the work ready after a blanket commit, revert, clean, or stash, and do not include ignored generated or unrelated local IDE state in the readiness change set.

Output Format

Use a compact readiness report:

• Status: ready / not ready / partially ready / blocked.
• Passed: checks, inspections, browser review, CI, or manual evidence.
• Failed: actionable failures with file/run links where useful.
• Pending: CI, review, deploy, indexing, or user decisions still in flight.
• Not run: checks skipped or unavailable, with reason.
• Next: the smallest concrete step to reach readiness.

If there are no blockers, say so plainly.