plan-review

# Plan Review Reviews PRDs, brainstorms, and technical plans using dynamically selected reviewer personas. Spawns parallel sub-agents that return structured JSON, then merges and deduplicates findings into a single report. ## When to Use - After writing a PRD - After writing a technical plan - When feedback is needed on any planning document - Can be invoked standalone or called by `iterative:brainstorming`/`iterative:tech-planning` skills ## Priority Scale All reviewers use HIGH/MEDIUM/LOW: | Level | Meaning | Action | |-------|---------|--------| | **HIGH** | Blocks execution; cannot start the next step without resolving | Must fix before proceeding | | **MEDIUM** | Creates risk; work can start but likely leads to rework or confusion | Should fix | | **LOW** | Improvement opportunity; plan works but could be clearer or tighter | Author's discretion | ## Reviewers 6 personas in three tiers. See `references/persona-catalog.md` for the full catalog. **Document-type (exactly 1 — selected by document type):** | Agent | Selected when | Identity | |-------|--------------|----------| | `prd-reviewer` | Document is a PRD or brainstorm | Senior product leader evaluating product document quality | | `tech-plan-reviewer` | Document is a tech plan | Implementer evaluating whether they can code from this plan | **Always-on (every review):** | Agent | Focus | |-------|-------| | `coherence-reviewer` | Internal consistency, contradictions, terminology drift, structural issues | **Conditional (selected per document):** | Agent | Select when document... | |-------|------------------------| | `skeptic-reviewer` | Proposes abstractions, multi-layer architecture, plugin systems, or infrastructure ahead of need | | `feasibility-reviewer` | Is a tech plan that proposes architecture, external integrations, or performance constraints | | `scope-guardian-reviewer` | Is a PRD with multiple priority levels and potential conflicts, unclear scope boundaries, many requirements where goal alignment isn't obvious, or goals that don't connect to requirements | ## Review Scope The document type naturally regulates the review. A simple PRD gets 2 reviewers (prd-reviewer + coherence-reviewer). A complex tech plan with architecture decisions gets 4 (tech-plan-reviewer + coherence-reviewer + skeptic-reviewer + feasibility-reviewer). No separate "mode" is needed. ## How to Run ### Stage 1: Identify document Identify the document to review from argument, conversation context, or ask user. Determine the **document type** — PRD, brainstorm, or tech plan — from filename, content, and context. Treat brainstorm documents and PRDs synonymously. Record the **document path** and **document type**. Read the full document content. This is needed for both reviewer selection and spawning. ### Stage 2: Select reviewers Read the document content from Stage 1. The document-type reviewer and coherence are automatic. For each conditional persona in the catalog (`references/persona-catalog.md`), decide whether the document warrants it. This is agent judgment, not keyword matching. Announce the team before spawning: ``` Review team: - prd-reviewer (document-type) - coherence-reviewer (always) - scope-guardian-reviewer — PRD has 12 requirements across 3 priority levels with dependency conflicts ``` This is progress reporting, not a blocking confirmation. ### Stage 3: Spawn sub-agents Spawn each selected reviewer as a parallel sub-agent using the template in `references/subagent-template.md`. Each sub-agent receives: 1. Their persona file content (identity, failure modes, calibration, suppress conditions) 2. The JSON output contract from `references/findings-schema.json` 3. Review context: document type, document path, document content Sub-agents are **read-only**: they review and return structured JSON. They do not edit files, run commands, or propose fixes. Each sub-agent returns JSON matching `references/findings-schema.json`: ```json { "reviewer": "prd-reviewer", "findings": [...], "residual_concerns": [...] } ``` ### Stage 4: Merge findings Convert multiple reviewer JSON payloads into one deduplicated, confidence-gated finding set. 1. **Validate.** Check each output against the schema. Drop malformed findings (missing required fields). Record the drop count. 2. **Confidence gate.** Suppress findings below 0.50 confidence. Record the suppressed count. 3. **Deduplicate.** Compute fingerprint: `normalize(section) + line_bucket(line, ±5) + normalize(title)`. When fingerprints match, merge: keep highest priority, keep highest confidence with strongest evidence, union evidence, note which reviewers flagged it. 4. **Promote residual concerns.** Scan residual_concerns for issues that overlap with findings from other reviewers or that describe concrete blocking risks (missing dependencies, unowned prerequisites, timeline impossibilities). Promote these to MEDIUM findings with confidence 0.55-0.65. A residual concern that corroborates an existing finding strengthens the case; one that identifies a distinct blocking risk deserves to be surfaced rather than buried. 5. **Sort.** Order by priority (HIGH first) → confidence (descending) → document order. 6. **Collect coverage data.** Union remaining (non-promoted) residual_concerns across reviewers. ### Stage 5: Synthesize and present Assemble the final report using the template in `references/review-output-template.md`: 1. **Header.** Document path, type, reviewer team with per-conditional justifications. 2. **Findings.** Grouped by priority (HIGH, MEDIUM, LOW). Each finding shows section, issue, reviewer(s), confidence. 3. **Coverage.** Suppressed count, residual concerns, failed/timed-out reviewers. 4. **Synthesis.** Patterns, tensions between reviewers, quick wins. Not a binary verdict — plans don't have "ready/not ready." The synthesis helps the author decide what to address. Do not include time estimates. ## After Review **When invoked from `iterative:brainstorming` or `iterative:tech-planning`:** return findings directly — the calling skill owns the fix loop and workflow transitions. Do not enter the standalone fix loop below. **When invoked standalone:** run the standalone fix loop. ### Standalone Fix Loop After presenting the synthesized findings (Stage 5), offer to fix issues when running standalone. Plan fixes are text edits with low cascading risk — keep the loop simple. If zero findings, the review is done — no further prompts needed. #### Step 6: Fix Offer **Use the platform's interactive question tool** — `AskUserQuestion` (Claude Code) or `request_user_input` (Codex). Both platforms provide an automatic "Other" free-form option — do not add one manually. Present a **single prompt** listing all priority levels with findings. No intermediate "choose which..." step. **Claude Code** — use `AskUserQuestion` with `multiSelect: true`: When HIGH issues exist, pre-check the HIGH option: - ☑ **HIGH (Recommended)** — N issues that block execution - ☐ **MEDIUM** — N issues - ☐ **LOW** — N issues When only MEDIUM/LOW issues exist, nothing pre-checked: - ☐ **MEDIUM** — N issues - ☐ **LOW** — N issues Only include priority levels that have findings. **Codex** — use `request_user_input` (single-select, build combined options): When HIGH issues exist: - **Fix HIGH (Recommended)** — N issues - **Fix HIGH + MEDIUM** — N issues - **Fix all** — N issues - **Skip fixes** When only MEDIUM/LOW issues exist: - **Fix MEDIUM only** — N issues - **Fix MEDIUM + LOW** — N issues - **Skip fixes** Only include options where findings exist at those levels. Omit options that would duplicate another (e.g., if no LOW, omit "Fix all" since it equals the line above). #### Step 7: Apply Fixes Fix only the selected priorities. Spawn a single subagent with the filtered findings, document path, and document type. The subagent applies targeted fixes, preserves the document's voice and decisions, and commits. Wait for the subagent to complete. #### Step 8: Done After fixes land (or user skipped), present an interactive choice: - **Another review round** — fresh reviewers on the updated document - **Done** — review complete If another round: run the full Stage 1–Step 8 flow again. No workflow transition options — the user knows what to do next. ## Fallback If the platform doesn't support parallel sub-agents, run reviewers sequentially. Everything else (stages, output format, merge pipeline) stays the same.