peer-review-plan

Precondition (REFUSE if not met)

1. Identify the investigation id. If unclear, list findings/* and use AskUserQuestion to ask.
2. Read findings/<id>/plan.md. Must exist with status: draft or status: reviewed.
3. Read findings/<id>/brief.md. Must exist with status: approved — the brief is the contract the plan delivers against. If the brief is not approved, refuse and tell the user to approve the brief first.

What you do

You audit the plan, close gaps, and produce a tighter plan. The user reviews what you hand back. Catch what the plan writer missed.

Gap categories to check

Per-item output schema

• gap if: missing entirely; mandatory sections are generic ("Notes", "Insights") that verify-step can't check; doesn't match the brief's deliverables
• clean if: derived from the brief; every row has all five columns; mandatory sections are concrete and verifiable

Phase A signals

• gap if: vague ("find all the handlers"); no concrete regex or glob; no scope exclusions
• clean if: at least one literal pattern per signal; scope inclusions and exclusions named; per-signal verification

Phase B steps

• gap if: don't name input files; output file doesn't match a schema row; format described as "prose" with no structure detail; strategy steps propose one option
• clean if: every step has concrete inputs / output file (matching schema) / format (referring to the schema row) / verification; strategy steps force 2–4 options

Verification clauses

• gap if: unfalsifiable ("the output is correct"); self-referential ("check X by reading X"); vague
• clean if: a hostile reviewer could use the verification to prove the step was done wrong (see VERIFICATION-FORMAT.md)

Phase C — Synthesis

• gap if: "synthesize findings" with no structure; no minimum supporter count for themes
• clean if: theme criteria explicit (e.g. min 2 supporters); output file and format named

Phase D — Final strategy

• gap if: doesn't map to the brief's "decision this feeds"
• clean if: every recommendation maps back to a brief decision

Overall shape

• gap if: total plan under 200 lines for a non-trivial investigation (rule of thumb — under-length usually means under-specified); batching not declared when Phase A signals will obviously discover >5 items
• clean if: length proportional to brief scope; batching declared where the population will be large

How to close each gap

For every gap, try in this order:

1. Re-read brief.md. Many plan gaps are downstream of a brief detail the plan writer missed.
2. Read the codebase. If "scope" or "in_scope paths" are vague, grep first.
3. Re-read findings/<id>/items/... from a prior run if one exists. Plan refinements often look like prior runs.
4. Grill the user. Only when 1–3 can't close the gap. Use AskUserQuestion with 3–4 multi-choice options and a recommendation. Typical plan-grilling questions:
   • "Phase B will produce ~12 items. What batch size feels right?" (5 / 10 / one big batch — Recommended: 5 because subagent context stays manageable)
   • "Strategy options in Phase B3 — how many do you want per item?" (2 / 3 / 4 — Recommended: 3 because two forces a false binary, four spreads attention)
   • "The brief is silent on what 'public ingress' means for severity scoring. Define it as: ..."

When a gap is closed autonomously, edit plan.md in place. When you grill the user, append the Q&A to grilling.md under ## Plan refinement Q&A (from peer-review-plan) so the trail stays in one file.

Iteration

Same loop as peer-review-brief. Max 3 iterations. After 3, surface remaining gaps to the user via AskUserQuestion and let them choose Answer now / Accept with gaps flagged.

When you're done

Set plan.md frontmatter to status: reviewed. Hand back to the orchestrator.

Failure modes

• Padding the plan to hit a line count. Specificity is the goal, not length. Don't add boilerplate to look longer — fix the gaps that matter.
• Inflating the per-item schema. A schema with ten files per item is not better than one with four. Each row needs a distinct job.
• Skipping the verification audit. Vague verifications are the single biggest reason plans look fine and execute badly. Hit these hardest.
• Inventing patterns to fill Phase A signals. Read the codebase first. If you can't find the right pattern, ask.
• Becoming a second grilling phase. Most gaps close from re-reading the brief and the codebase. User-grilling is the fallback.