Check Plan

Plan and spec review (/check-plan)

Validate an implementation plan before it is executed, or a spec before it is built. The output is a verdict, a set of evidenced findings, and, where warranted, a corrected document.

Announce: "Reviewing the {plan|spec}: ground-truth pass, then the review panel."

The one rule everything else serves: a finding without evidence does not reach the document. A document updated from ungrounded findings is worse than an unreviewed one, because it now carries the appearance of vetting.

Hard rules

• Only you write. Reviewers return text; you apply every edit. Not a tool limitation, background subagents do keep Edit and Write, but a deliberate one: several reviewers editing one document concurrently corrupt it, and every finding must survive the Step 5 rejection pass before any of it lands.
• Read-only against git. Never stash, never commit, never push, never switch branch. The working tree may hold another session's uncommitted work.
• Missing evidence is a coverage limitation, not a defect. A reviewer that crashed, a doc that 404s, a command that failed: report reduced confidence. Never convert a tool failure into a finding against the document.
• Returning READY is a real result. Do not manufacture findings to justify having run.

Step 0. Resolve the document and its type

Take the document from the file path given, or from the conversation. Record which.

If there is no concrete document, stop with BLOCKED. Do not invent one in order to have something to review.

Detect the type. It changes the perspective menu and the adversarial contract. Nothing else in this skill varies.

Mixed documents exist. Judge by which half carries the risk: a spec with a short task list appended is still a spec. When genuinely ambiguous, state which you chose and why in one line, then proceed.

Throughout the rest of this skill, the document means whichever you resolved.

Create a scratch directory for this run inside your session scratchpad.

Step 1. Ground truth (before any reviewer is dispatched)

This step is the difference between a review and a conversation about a review. Do it yourself, first, and give the result to every reviewer so none of them waste a turn re-deriving it.

Identical for plans and specs. Only the targets differ: a plan names what it will change, a spec names what must be true. Both name things that have to exist.

1a. Existence ledger. Extract every path, file, symbol, function, route, command, environment key, dependency and version the document names. Verify each against the repository as it is right now. Build a three-column table:

Anything the document treats as existing but that does not exist is a BLOCKER before review starts. Mark genuinely new artifacts as new so no reviewer reports them as missing.

1b. Re-derive every enumeration. Allowlists, file lists, route tables, env-var lists, migration lists, and in a spec also the decision list, the copy artifacts, and the out-of-scope list. Either document freezes the codebase as it was the day it was written; anything that shipped since is missing from its lists. Do not read the enumeration and nod. Regenerate it from current code and diff.

This is the highest-yield check in the whole skill. The shape of the failure it catches: a security-headers plan carrying a CSP allowlist that was complete when it was written, and is now missing the object-storage origin added since. Every line of the plan reads correctly. Executing it silently breaks every upload. Nothing but regenerating the list against current code finds that.

1c. Sibling work. Concurrent sessions share this working tree. Check for plans, branches or edits that touch the same surfaces:

git status --porcelain
git log --oneline origin/main..main
git diff --name-only origin/main..main
git branch -a --sort=-committerdate | head -15

Also scan sibling plans and specs in the same directory, and the spec this plan derives from or the plan derived from this spec, for shared files, contracts, schemas, or the same trigger with a conflicting outcome. Keyword similarity is a lead, not a finding. Two documents writing the same surface is a BLOCKER, and a plan that has drifted from its own spec is a BLOCKER against whichever of the two is being reviewed.

1d. Conventions. Read the applicable CLAUDE.md, root and nested, for every directory the document touches. Reviewers judge against these, not generic best practice.

Step 2. Classify

• Document type: plan or spec, from Step 0.
• Domain: implementation, migration, refactor, research, design, ops.
• Risk class: high if it touches auth, authorization, money, destructive operations, data migration, public APIs, concurrency, or irreversible rollout. Otherwise medium, or low when local and reversible.

Document type selects which perspective menu applies. Risk class sets panel size and how many perspectives run adversarially. Both menus are in references/agent-prompts.md.

Step 3. Dispatch the panel

Read references/agent-prompts.md and use the menu matching the document type from Step 0. Pick perspectives for coverage of what the document actually touches, assign each collaborative or adversarial mode, and launch them in parallel in a single message.

Every agent gets the full document text pasted in, the relevant conventions, and the Step 1 ledger. Subagents have none of your context; a reference to "the document" is a reference to nothing.

Step 4. Synthesize

Collect the panel, then, in order:

1. Reject. Drop findings that are unsupported, that state taste as fact or style as requirement, that recite generic best practice with no demonstrated connection to this document, that justify architecture by hypothetical future scale, or that raise pre-existing adjacent problems failing the scope rule in references/agent-prompts.md. Rejection happens before deduplication so noise does not survive by being reported twice.
2. Check evidence. Every surviving finding must carry a file:line, a command with real output, or an official doc URL, and that evidence must actually support the claim. Drop the rest. A confident sentence is not evidence.
3. Deduplicate. Keep the strongest evidence for each. Preserve genuine disagreements rather than averaging them; note them explicitly.
4. Classify. BLOCKER prevents safe execution. MAJOR predicts substantial rework or regression. MINOR improves clarity without changing feasibility.

Step 5. Verdict

Step 6. Apply and log

Apply. Edit the document yourself. Incorporate every BLOCKER and MAJOR. Use judgment on MINOR. Do not expand scope: a review that grows the document has failed, even when each addition is individually defensible. On a spec this is the easiest rule to break, because "the spec should also say X" always sounds reasonable; it is only a finding if the absence of X makes the spec unbuildable or ambiguous, not if X would merely be nice to have written down.

Log. Append this round to <doc-dir>/reviews/<doc-basename>-review.md, creating it if absent. Rounds are separated by --- and appended at the end, never rewritten. If the document came from the conversation rather than a file, skip the log and say so.

---

## Round {N} - {YYYY-MM-DD}

**Verdict:** {verdict}
**Panel:** {perspectives, mode each}

### Previous round tracking (round 2+)
| # | Finding | Status | Notes |
|---|---|---|---|

### Findings
#### [SEVERITY] {title}
- Location, Evidence, Impact, Required change

### Verified
{claims checked and found correct}

### Out of scope
{adjacent problems deliberately not made findings}

### Coverage limitations
{what could not be verified, and why}

On round 2 or later, read the existing log first and track what the previous round found: fixed, still open, or rejected with a reason. Paste that tracking table into every panel prompt, so reviewers spend the round on what moved rather than re-deriving last round's findings and reporting them again as new.

Step 7. Report

State, briefly: the verdict, what changed in the document, what was verified, where reviewers disagreed and how you resolved it, and what remains unverified. Findings first, most severe first. Then the log path.

Documents with little repository surface

The ground-truth pass still applies, with different targets. For a research document, verify the sources, tools and APIs it names exist and say what it claims. For a design document, verify the components, tokens and routes it references. For a migration document, verify the current schema state rather than the state it assumes.

Drop perspectives that have nothing to check rather than running them to fill the panel. Say which you dropped and why.

Credits

Adapted from replan in the claude-replan plugin (v1.1.0) by Jiri George Dolejs, MIT + Commons Clause. Taken from it: the dispatcher shape - coordinator classifies, a panel of parallel perspectives runs, coordinator merges - the coordinator as the only writer, documents that are not about code treated as first-class, and shipping the subagent prompts as copyable artifacts rather than leaving packet construction to improvisation. The text here has since been rewritten end to end; nothing upstream loads at runtime.

Evidence discipline came from reading ln-11-plan-reviewer in levnikolaevich/claude-code-skills (plugins/review-suite), never installed: findings must carry evidence or be dropped, the mandatory pre-dispatch existence ledger (Step 1a), the four-verdict scale including BLOCKED, the finding-rejection and pre-existing-problem scope rules, and the sibling-work collision check.

Smaller grafts: collaborative and adversarial as two distinct modes, from dsifry/metaswarm; the "do not trust the planner, verify every claim" adversarial mandate, from abadcafe/superteam; the persistent round-tracking review log, from longranger2/claude-gpt-workflow.

Spec mode is from neither source.

2026-07-31: an independent cross-model reviewer tier ran Codex against the repository on an OpenRouter pin, with a same-model subagent as fallback. Removed along with its --output-schema file: it made the codex CLI, an OpenRouter account and a funded key prerequisites for a clean run, and degraded quietly when any of the three was missing. The panel is now the whole review.