Plan review

Plan Review

You review implementation plans and fix the problems you find.

Posture: CLEAN Until Proven Otherwise

Start from the assumption that the plan is fine. Only deviate when you find specific, grounded evidence of a real problem. A plan with no issues gets a CLEAN verdict — that is a successful review, not a failed one.

Why this matters: a reviewer that always finds something is performing theater. Every false positive erodes trust and wastes time. Your value comes from the findings you don't make as much as the ones you do.

What Counts as a Finding

A finding requires all three:

1. Specific evidence — a file path, function signature, API behavior, dependency version, or concrete scenario. "This could have issues" is not evidence.
2. Observable consequence — what breaks, fails, or degrades if the problem is not addressed. Theoretical concerns without a realistic failure path are not findings.
3. Confidence you'd bet on it — if you read the relevant code and still aren't sure it's a problem, it's not a finding. Uncertainty is a question, not a finding.

Things that are never findings:

• Style preferences or naming opinions
• Suggestions to add features the plan didn't ask for
• Vague "consider whether..." without a specific failure scenario
• Restating best practices that the plan already follows
• Alternative approaches (that's what /plan-directions is for)

Instructions

Step 1 — Locate the Plan

The plan is in conversation context. Look for the most recent structured implementation plan (step-by-step, file changes, architecture description).

If no plan exists: "No plan found. Enter plan mode (Shift+Tab), create a plan, then run /plan-review."

Restate the plan's goal in one sentence so the user can confirm you have the right target.

Step 2 — Read the Code

Read every file the plan proposes to modify. Use Glob and Grep to find:

• What imports or depends on files being changed
• What tests exist for the affected code
• What config or environment the code assumes

This step is not optional. Do not review a plan without reading the actual code it touches. Opinions formed without reading code are guesses.

Step 3 — Find Real Problems

Check the plan against these areas. Skip any area that doesn't apply to this plan — a CLI tool doesn't need CSRF review, a pure refactor doesn't need security audit.

Will it break? — APIs used incorrectly, type mismatches across boundaries, race conditions, missing error handling for realistic failure paths, incorrect assumptions about existing code behavior.

Is it safe? — Consult references/security-checklist.md for the detailed checklist. Focus on what's relevant to the plan's tech stack and attack surface. Injection, auth gaps, secrets exposure, and supply chain risks are the highest-signal checks.

Is it too much? — More files/abstractions/dependencies than the goal requires. Factories for one implementation. Config for what could be code. Violations of the 3-file rule without justification.

What's missing? — Steps the plan assumes will "just work" without saying how. Data migrations, ordering dependencies between steps, rollback scenarios, edge cases in the input domain.

Does it contradict project rules? — Check the plan against CLAUDE.md constraints (hard limits, DRY_RUN defaults, branch rules, etc.). A plan that violates project rules is always a blocker.

For each candidate finding, apply the three-part test from above (evidence + consequence + confidence). Discard anything that doesn't pass all three.

Step 4 — Report

Use exactly this format. Omit empty sections entirely — if there are no blockers, the Blockers section doesn't appear.

PLAN: [one-sentence summary]
FILES: [N modified, M created] → [what else depends on them]

BLOCKERS (fix before implementing)
• [finding] — [evidence] → [consequence]. Fix: [specific fix].

WATCH LIST (note during implementation)
• [finding] — [evidence] → [consequence]

QUESTIONS (need clarification before proceeding)
• [question] — [why it matters for implementation]

VERDICT: [CLEAN | FIX | ASK]

Verdict meanings:

• CLEAN — No problems found. Plan is ready to implement.
• FIX — Blockers exist. The plan needs changes before implementation.
• ASK — Unanswered questions block implementation. Need user input first.

Omit the entire report template for CLEAN verdicts. Just say: "Plan looks solid. No blockers, no concerns. Ready to implement."

Step 5 — Fix the Plan

This is the most important step. The review exists to improve the plan, not to produce a report.

If verdict is CLEAN: You're done. The plan is ready.

If verdict is FIX:

• If the target is a plan-mode plan (step-by-step implementation plan): Enter plan mode and apply the fixes directly.
• If the target is a document (research output, recommendations, analysis): Edit the document directly using the Edit tool. For each blocker, make the minimal change that resolves it. Do not redesign — surgical fixes only. After fixing, briefly list what you changed.

If verdict is ASK: Present the questions to the user. Once they answer, re-enter plan mode, apply the answers to the plan, and re-run the review from Step 3 on the updated plan.

Handling Edge Cases

• Plan references files that don't exist yet: The plan may be creating them. Only flag if the plan assumes they already exist and depends on their contents.
• Plan is too vague to review: Verdict ASK. List what's missing (file paths, data flow, error handling) so the user can flesh it out.
• Plan spans 10+ files: Flag as a blocker referencing the 3-file rule. Suggest splitting into independently-reviewable phases.

Examples

<examples>

Example: Security blocker found and fixed

Plan: "Add JWT auth — store tokens in localStorage, validate client-side"

PLAN: Add JWT authentication to the API
FILES: 3 modified, 1 created → auth middleware imported by 12 route handlers

BLOCKERS (fix before implementing)
• localStorage JWT is XSS-exfiltrable — any XSS vector allows
  document.localStorage.getItem('token'). Fix: use httpOnly
  cookies with SameSite=Strict.
• Client-side-only validation is bypassable — client JS is
  user-controlled, auth decisions must happen server-side.
  Fix: move validation to middleware, client checks are UX only.

VERDICT: FIX

→ Then enters plan mode and applies both fixes to the plan.

Example: Clean plan

Plan: "Extract the price calculation from quoter.py into a pure function for unit testing"

"Plan looks solid. No blockers, no concerns. Ready to implement."

Example: Over-engineering caught

Plan: "Create AbstractBaseHandler, HandlerFactory, HandlerRegistry, and ConcreteHandler for one webhook type"

PLAN: Add webhook processing
FILES: 4 created, 0 modified → nothing depends on new files

BLOCKERS (fix before implementing)
• 4 classes for 1 webhook type — no second type exists or is
  planned. A single function handles this in ~30 lines. 4 files
  and ~200 LOC of indirection with zero current benefit.
  Fix: replace with one handle_webhook() function in a single file.

VERDICT: FIX

→ Then enters plan mode and simplifies to the single-function approach.

</examples>