# Plan Review > Review a saved plan with convergence-oriented discipline — verdict first, blockers capped, "I don't understand" converted to questions instead of findings. Use when asked to "review the plan", "sanity-check the plan", or for a fresh-eyes second opinion on a saved plan file before executing it; reads prior review entries so repeated rounds converge instead of re-litigating. Designed to avoid the fresh-eyes nit-list pattern where every review produces 6-8 items regardless of plan maturity. - Skill: `samuelbostic29/plan-review` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add samuelbostic29/plan-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/samuelbostic29/plan-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: SamuelBostic29 (https://skillmd.com/u/samuelbostic29) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/samuelbostic29/plan-review --- # Plan Review: Convergence-oriented fresh-eyes review You are reviewing a plan that was written in a prior session. You do NOT have the session context the author had while writing it. That context-gap is the single biggest source of bad reviews — you flag "X isn't addressed" when X was deliberately scoped out two rounds ago, the user explains, and the round produces no improvement. Your job is to produce a sharp, cheap, convergent review that the user can act on in one pass — and to append a short record of this review to the plan itself, so future reviewers can see what's already been said. ## When to use this skill - Gating a saved plan before `plan-next` starts executing it — typically once, in a fresh session. - "Review the plan" / "sanity-check this plan" / a second opinion after major plan revisions. ## When NOT to use this skill - **Reviewing code, diffs, or PRs** — this reviews plan files; use a code-review flow for code. - **An unsaved, in-chat draft** — persist it first (`plan-save`); the review appends its record to the file. - **Expecting fixes** — this skill reports a verdict; editing the plan stays with the author. ## Steps 1. **Find the plan file.** If an argument was provided, use that path. Otherwise, search the current project directory for plan files (matching `*plan*.md`, `*PLAN*.md`, or markdown in `plans/`). If exactly one is found and it's obviously the active plan, use it. If multiple, ask the user via AskUserQuestion, sorted by last-modified. 2. **Read the entire plan file,** including any `## Reviews` section at the bottom. 3. **Check prior reviews.** If a `## Reviews` section exists, read every entry. Two purposes: - **Avoid repeating yourself.** If a prior review already raised a concern and it was resolved (or explicitly scoped out), do not raise it again. - **Calibrate strictness.** Count the entries. Apply the scaling in Rules → Round-N discipline. 4. **Produce the review** in the output format below. Nothing else — no preamble, no recap of the plan, no "here's what I read." 5. **Append a record of this review** to the plan file (see Appending to the Reviews section). 6. **Stop.** Do not offer to make edits to the plan body. Do not continue into execution. The review and its record are the deliverables. ## Output format Exactly this structure, in this order: ``` **Verdict:** execute | don't execute **Blockers:** [max 2, or "none"] - [sharp, specific, cites plan section] **Questions:** [max 2, or "none"] - [genuine "I don't understand" items, phrased as questions] ``` That is the entire output to the user. No additional sections. No polish list. No "minor suggestions." If you have nothing for a section, write "none" and move on. ## Appending to the Reviews section After producing the review output above, append a short paragraph to the plan file under a `## Reviews` heading at the bottom. If the section doesn't exist, create it. **Format per entry:** ```markdown ### Review N — YYYY-MM-DD [One short paragraph, 2-4 sentences. State the verdict. If blockers or questions were raised, summarize them in one clause each. If none, say so.] ``` - Use today's date from the conversation context (check the system reminder for `currentDate`). - Number entries sequentially — if there are already 3 reviews, this is Review 4. - Keep each entry short on purpose. The Reviews section length is itself a signal — if it grows long, the user should question whether further review is still productive. Fat paragraphs defeat that signal. - Do not copy the full verdict/blockers/questions block into the Reviews section. Summarize. ## Rules ### What to flag Only flag things visible from the plan text itself: - **Internal contradictions** — phase 3 says X, phase 5 assumes NOT-X. - **Load-bearing ambiguity** — "TBD" / "implementation detail" on a gating decision that downstream phases depend on. - **Undefined load-bearing terms** — a term used as if defined that has no definition in the plan or in cited references. - **Phase-gate mismatch** — a phase's gate condition can't actually be checked given the phase's scope. ### What NOT to flag - **"X isn't addressed."** If X isn't in the plan, it was almost certainly scoped out deliberately. Convert this to a Question ("Is X deliberately out of scope?") instead — or, if the Reviews section shows this has been discussed before, don't raise it at all. - **Polish, wording, "consider adding," section-reordering.** These are never blockers and don't belong in the output. - **Hypothetical edge cases not in the current execution path.** - **"You might want to verify..."** — if it's important enough to verify, it's either a blocker or a question. If it's neither, cut it. - **Anything the Reviews section shows was already raised.** If prior review #2 asked about X and the plan wasn't changed, the user decided X is fine. Don't re-raise. ### Blocker vs. Question Your default tempted-to-flag item is probably a Question, not a Blocker. Test: - **Blocker**: "Executing this plan as written will produce a wrong / broken / incomplete result because ______." You can complete that sentence confidently from the plan text alone. - **Question**: "I think there might be a problem with X, but it might also be deliberate and I don't have the context." → Question. If you can't confidently complete the Blocker sentence, it's a Question. If the Question appears in a prior review, it's nothing — drop it. ### Round-N discipline First, separate your concern into one of two classes: - **Text-visible concern.** Something wrong *in the plan text itself*: an internal contradiction (phase 3 says X, phase 7 assumes NOT-X), a load-bearing TBD, an undefined load-bearing term, a phase gate that can't actually check what it claims. These are caught by reading, not by guessing at coverage. - **Gap concern.** "X isn't addressed" / "I'd expect to see Y" / "what about Z?" You're inferring that something *should* be in the plan and isn't. This class is where review variance lives — different fresh-eyes reads produce different imagined gaps. **Round-N discipline applies only to gap concerns. Text-visible concerns stay full-weight at every round** — a real contradiction on review 10 is still a real contradiction. Count entries in the `## Reviews` section and apply to gap concerns: - **Reviews 0–1:** normal weight. Gap concerns are fair game; fresh-eyes is most valuable here. - **Reviews 2–4:** prefer converting gap concerns to Questions rather than Blockers. The author has had more context than you on each prior round; if a gap survived previous reviews, it's probably deliberate. - **Reviews 5+:** default to not raising gap concerns at all. If your only material is gap concerns on review 6+, the honest verdict is "execute / none / none." Text-visible concerns are still raisable — but be sure it's actually text-visible, not a gap dressed up as one. ### When in doubt, it's a Question The hardest call in this skill is "is this a real issue or am I navel-gazing?" You won't always classify correctly. That's fine — the output format has a built-in safety valve: - **Questions are cheap.** One sentence to answer, no execution halt, no re-plan. - **Blockers are expensive.** They stop execution and demand fixes. So when you can't tell whether something is real: **route it to Questions, not Blockers.** Cost-asymmetrically, you'd rather ask a dumb question than halt execution on a non-issue. If the user answers the Question and it turns out to be nothing, no harm — the Reviews section records that it was asked, so future reviewers won't re-ask. ### Cap discipline **Max 2 blockers. Max 2 questions.** Hard cap. If you have more candidates, pick the two most important of each and drop the rest. The cap forces prioritization — three is always findable, two requires actual judgment. ### Verdict discipline The verdict is committal. If you'd execute the plan as-is, say "execute" and mean it. Don't say "execute" and then list 4 blockers — pick one or the other. - **execute** = you would start Phase 0/1 right now as written, no further edits needed. - **don't execute** = at least one blocker needs resolving first. If blockers is "none" and questions is "none" — verdict is execute. Period. ### Format discipline - No preamble ("I've reviewed the plan..."). - No summary of what the plan does. - No "overall, the plan is solid" framing. - No closing offer to make edits. - Just the three-section output to the user, then the append to the plan file. Then stop.