# Check Plan

> Review and validate an implementation plan or a spec/design doc before it is built, using a mandatory repository ground-truth pass and a panel of parallel reviewers. Use whenever a plan is about to be executed, whenever a spec is about to be turned into a plan or into code, when either was written more than a day ago, or when the user invokes /check-plan. Applies to any domain - implementation, migration, refactor, research, design, ops.

- Skill: `marekpolcar/check-plan` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add marekpolcar/check-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marekpolcar/check-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: marekpolcar (https://skillmd.com/u/marekpolcar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/marekpolcar/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.

| Type | Shape | Contract being tested |
|---|---|---|
| **Plan** | Ordered tasks, file-by-file changes, a sequence someone executes | Can this be executed against this repository and reach the goal? |
| **Spec** | Goal, decisions, artifacts, surfaces, out of scope, verification. No ordering | Can two competent implementers read this and build the same thing? |

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:

| Named in document | Exists | Evidence |
|---|---|---|
| `apps/api/src/routes/checkout.ts` | yes | read, 412 lines |
| `buildFlyerPrompt()` | moved | now `apps/api/src/prompts/flyer.ts:31` |
| `STRIPE_WEBHOOK_SECRET` | no | absent from `.env.example` and compose |

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:

```bash
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

| Verdict | When | What you do |
|---|---|---|
| `READY` | No corrective finding, no blocking evidence gap | Say so, list what was verified, change nothing |
| `READY WITH CONCERNS` | Safe and executable; only bounded MINOR amendments or accepted residual risk | Apply the amendments only |
| `REVISE` | Any correctable BLOCKER or MAJOR | Apply corrections to the document |
| `BLOCKED` | A required user decision, access, or authoritative fact is missing, or no concrete document exists | Change nothing; ask only the smallest questions that would materially change the document, and state what you already verified |

## 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.

```markdown
---

## 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`](https://github.com/kojott/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`](https://github.com/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.