Review Plan

Adversarial review loop for a plan document. Each round: a fresh subagent reviews the file, you triage its findings, apply only the ones that hold up, and repeat. Stop on explicit approval or after the iteration cap.

Arguments

/review-plan [flags] <path-to-plan.md> [extra focus notes]

No path given: infer the plan file from conversation context (the doc just written or discussed). If genuinely ambiguous, ask.

Procedure

Repeat up to N rounds (default 3):

1. Launch reviewer subagent

Fresh agent per round — never reuse the previous reviewer, so each round reads the document cold, the way a new implementer would. Prompt template (adapt paths/focus):

Review <plan-path> as a skeptical senior engineer who must implement it tomorrow. Identify:

• Gaps — missing steps, unhandled cases, undefined interfaces, absent success criteria
• Assumptions — anything taken as true but unverified (APIs, data shapes, perf, team capacity)
• Limitations — scope constraints or trade-offs the plan doesn't acknowledge
• Mistakes — factual/technical errors, contradictions, infeasible steps
• Ambiguities — anything two implementers would interpret differently

For each finding: severity (blocker / major / minor), the exact section/line, and a concrete suggested fix. Verify claims against the actual codebase where the plan references real files or APIs — do not take the plan's word for it.

End with an explicit verdict on its own line: VERDICT: APPROVED (ready to implement as written) or VERDICT: NOT APPROVED (blockers or majors remain). Approve only if you would start implementing without further questions.

If a designated reviewer agent type exists in this session (e.g. a reviewer subagent), it may be used; otherwise general-purpose (or fork when session context matters).

2. Triage the review

You are the editor, not a stenographer. For each finding, judge:

• Apply: real gap/error/ambiguity a fresh implementer would hit. Concrete, correct, actionable.
• Reject: reviewer misread the doc, invented a requirement, restated a deliberate scope decision as a flaw, nitpicked style, or proposed scope creep. Low-value or wrong findings get dropped — do not pad the plan to appease the reviewer.

When rejecting a blocker/major, note the reason in one line (for the final report), since ignoring a blocker is a judgment call the user should see.

3. Address accepted findings

Edit the plan file directly. Keep the document's voice and structure; strengthen, don't bloat. If a finding requires information you can get (read code, check an API), get it and resolve the point rather than adding a "TBD".

4. Check exit condition

• Reviewer said VERDICT: APPROVED — stop, report.
• Round cap reached — stop, report remaining open items.
• Otherwise — next round with a fresh reviewer.

Final report

Short summary to the user:

• Rounds run, final verdict.
• Per round: findings applied vs rejected (counts + the notable ones, one line each).
• Rejected blockers/majors with the one-line reason.
• If not approved at cap: what's still open and your own judgment on whether it's ready to implement anyway.

Notes

• Reviewer reads the file fresh each round; never paste the plan into the prompt if the agent can read it from disk.
• Each round reviews the current on-disk version, including your edits from prior rounds.
• Don't let rounds converge on churn: if round N's review only surfaces restyled versions of already-rejected findings, stop early and report — more rounds won't help.
• This skill runs synchronously in the session (not a /loop or cron); each round's triage is your judgment call in-context.