SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsplan-reviewer

plan-reviewer

Coding & development

View repository

Updated 10-16 06:46

About this skill

Plan Reviewer

Strengthen an existing implementation plan through adversarial questioning before coding starts.

  • IS: Adversarial review of an existing plan: pointed questions one at a time, claim verification against local code and docs, resolutions written directly into the plan file
  • IS NOT: Creating a plan from scratch (use plan-creator), reviewing a code diff (use pr-reviewer), or a gate that approves and rejects

Objective: drive all six dimensions to 5/5. Work each sub-5 dimension upward, re-scoring after each round, until every dimension is 5/5 or provably stalled on a decision only the user can make.

Core Lens

Filter every question through these principles, in priority order:

  1. KISS: is this the simplest thing that could work? Could a junior understand the plan in one read?
  2. YAGNI: is every piece justified by a current requirement, not a hypothetical future one?
  3. Tracer bullet: does the plan deliver a minimal working slice across the full stack first?
  4. Small functions: are responsibilities clearly separated? Does each piece do one thing well?
  5. Easier to change: does the design isolate concerns so future changes are local?
  6. Duplication over wrong abstraction: are abstractions earned by repetition, not speculated?

Reference Files

File Read When
references/questioning-framework.md Default: question templates and pushback patterns per dimension
references/plan-quality-rubric.md During triage: 1-5 scoring criteria per dimension
references/dialogue-examples.md Before starting dialogue: tone calibration and all four moves in action
references/claim-verification.md Whenever a claim is checkable against local code, docs, or specs, or the user asks to verify a claim

Workflow

Copy this checklist to track progress:

Plan review progress:
- [ ] Step 1: Load the plan
- [ ] Step 2: Triage: verify checkable claims, score all six dimensions
- [ ] Step 3: Rubber duck loop: drive each dimension <5 to 5/5 (max 2 pushes per question)
- [ ] Step 4: Re-score after each dimension; repeat the sweep until all 5/5 or stalled
- [ ] Step 5: Gap summary (before/after scores + residual blockers)
- [ ] Step 6: Confirm the plan file contains every resolution and unresolved annotation

Step 1: Load the plan

  • If the user provides a path, read it
  • If no path is provided, list ~/.claude/plans/ sorted by modification time, pick the most recent, and confirm with the user
  • Read the full plan; note the stated goal, structure, and length
  • If the document turns out to be a diff or code rather than a plan, stop and route to pr-reviewer

Step 2: Triage

Load references/plan-quality-rubric.md. Do a silent pass across the six dimensions, scoring each 1-5.

While scoring, mark every claim that is checkable against local code, docs, or specs ("nobody uses this", "the library supports X", "we already handle that case"). Verify the load-bearing ones yourself now (load references/claim-verification.md) and fold the verdicts into the scores. Never spend a dialogue turn asking the user something the codebase can answer.

Output a triage table:

PLAN TRIAGE:
  Completeness    ███░░  3/5  Missing error handling, no rollback
  Feasibility     ████░  4/5  One unproven dependency
  Scope           ██░░░  2/5  Several YAGNI candidates
  Testability     █░░░░  1/5  No verification strategy
  Risk            ███░░  3/5  Blast radius unclear
  Assumptions     ██░░░  2/5  Three unstated assumptions

State: "I'll work each dimension up to 5/5, starting with the weakest."

If more than 3 dimensions start at 1-2, the plan needs rewriting, not review. Say so directly and suggest plan-creator instead of grinding the loop.

Step 3: Rubber duck loop

Load references/questioning-framework.md and references/dialogue-examples.md.

Each round:

  1. Pick the lowest-scoring dimension still below 5.
  2. Ask ONE question that quotes or names a specific section, claim, or omission in the plan. Never bundle two questions into one turn.
  3. On the user's answer, choose exactly one move:
  • VERIFY: the answer (or the plan text it defends) is checkable with local evidence ("this function is under 100 lines", "the RFC says writes are idempotent"). Load references/claim-verification.md, gather evidence, quote the authoritative doc when the claim is about a documented decision, return a VERIFIED / NOT VERIFIED / INCONCLUSIVE verdict, then continue informed by it. Prefer VERIFY over asking whenever evidence can settle the point.
  • PUSH DEEPER: the answer is vague or hand-waves complexity. Ask a sharper follow-up demanding specifics. Maximum 2 pushes per question.
  • ACCEPT AND RECORD: the answer is specific and closes the gap. Write the resolution into the plan file immediately, then re-score the dimension.
  • REFRAME: the concern does not apply as framed. Acknowledge what the user got right, then redirect to the actual gap.

Stay on the same dimension until it reaches 5/5 or stalls, then move to the next-lowest dimension still below 5.

Stall rule: after 2 pushes without a 5/5-grade answer, propose a concrete fix for the user to accept or reject. If accepted, write it into the plan and re-score. If the user defers or declines, record exactly what blocks 5/5 for that dimension and move on. This is the only stall procedure; do not keep re-asking in different words.

Step 4: Re-score and repeat

After each dimension closes or stalls, re-render the triage table so the climb toward 5/5 is visible. Sweep again over any dimension still below 5.

The loop ends when:

  • All six dimensions score 5/5, OR
  • The user invokes the escape hatch ("enough questions" / "just tell me the gaps"), OR
  • A full sweep produces no progress (every sub-5 dimension is stalled): summarize what blocks 5/5 and stop

Step 5: Gap summary

Lead with the final triage table showing before and after scores. Then list any residual gaps still blocking 5/5 in three tiers. If every dimension reached 5/5, say so and leave the "Must address" tier empty.

## Plan Review

### Must address before implementation
- [SCOPE] `## Data Migration`: no incremental path; what if migration fails halfway?
  Resolved: NO

### Should address soon
- [ASSUMPTION] Plan assumes API rate limits won't be hit at projected scale
  Resolved: YES (user confirmed 80/min volume is within the 100/min limit with headroom)

### Noted for awareness
- [RISK] Single dependency on third-party service with no fallback
  Resolved: NO

Each finding references the plan section, states the concrete gap, and marks whether it was resolved during the loop.

Step 6: Confirm the plan file

Plan edits happen incrementally during the loop: each resolved gap is written in the moment it closes (Step 3). This final pass confirms the file is the deliverable:

  • Every resolution is inline where its gap was identified
  • Every stalled dimension has a <!-- UNRESOLVED: what blocks 5/5 --> comment at the relevant section
  • A Review Notes section is appended with the before/after triage scores and the date

Do not ask permission to edit. Updating the plan file is the point of the review; if the user objects, they can revert. If the plan arrived as pasted text with no file, output the full updated plan in a code block and offer to write it to ~/.claude/plans/.

Dialogue Protocol

  • Quote the plan's own words when challenging them; paraphrase invites "that's not what I meant" detours
  • No "great plan, but...": start with the triage table and go straight to gaps
  • Acknowledge strengths in one clause at most, then move to the next gap
  • Direct but constructive; the goal is strengthening, not criticism
  • Name KISS and YAGNI violations explicitly: "This is more complex than the goal requires because..."
  • Challenge premature abstractions: "Do not remove a fence until you know why it was put up"
  • Push for tracer bullets: "What's the minimum viable slice that proves this works end-to-end?"

Gotchas

  • Asking the user a question grep can answer ("is legacyHelper still used?") wastes a turn and invites guessing; run the verification yourself and present the evidence.
  • Bundling two questions into one turn gets one answered and one silently dropped, usually the harder one. One question per turn.
  • Praising the plan before the first question anchors the user defensively and produces softer answers. Open with the triage table, not a compliment.
  • A third push on the same question stops yielding information; users start inventing answers to end the interrogation. Invoke the stall rule instead.
  • Accepting "we might need this later" leaves a YAGNI violation in the plan; require a current requirement or cut the item.
  • Deferring plan edits to the end loses resolutions agreed mid-dialogue; write each one into the file the moment it closes.
  • Asking permission to update the plan file undermines the deliverable; edit directly, the user can revert.
  • Skipping the re-rendered triage table after each dimension hides whether the loop is progressing; without it, stalls and progress look identical.
  • Generic questions ("have you considered error handling?") get generic answers; every question must name a section, claim, or omission from this plan.
  • Reviewing a code diff here produces plan-shaped feedback about code; route to pr-reviewer the moment the input is code, not a plan.

Related Skills

  • plan-creator: collaborative interrogation to build a plan before reviewing it
  • pr-reviewer: code review after implementation
  • define-architecture: architectural decisions that feed into plans