القائمة
Use when a plan is complete (/plan finished), user says "review the plan", "check the plan", or before running /beads on a new plan.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | review-plan |
| description | Use when a plan is complete (/plan finished), user says "review the plan", "check the plan", or before running /beads on a new plan. |
| argument-hint | [feature-name] or path to plan directory |
Philosophy: A plan is the last line of defence before /beads generates executable work packages. Every claim in a plan — "FR-X is covered by T03", "this mirrors the design's feature decomposition", "dependencies form no cycles" — must be verified against the authority source, not taken at face value. The plan author (human or agent) has blind spots; this skill's job is to find them. Depth over breadth: two Critical design contradictions matter more than twenty Minor formatting issues.
Duration targets: BRIEF ~10-15 minutes (single overview file, fewer authority sources), STANDARD ~20-40 minutes (overview + sub-plans, full authority chain), COMPREHENSIVE ~40-90 minutes (full authority chain + companion docs + deep cross-reference). Most time should be spent on Phases 2 and 4 (design fidelity and PRD traceability) — these catch the errors that make /beads produce wrong code.
Plans that pass a cursory review but contradict the design produce beads that implement the wrong thing. A plan that claims FR coverage but maps FRs to tasks that don't actually address them creates false confidence. Phantom scope — tasks that appear in the plan but have no basis in any authority source — wastes execution time and pollutes the codebase. This skill exists because real-world plan reviews have caught: design decisions silently reversed, endpoints with wrong HTTP verbs, entity columns missing from data model tasks, Must-Have FRs mapped to tasks that only partially address them, and companion docs that contradict the design's test plan.
Run this skill when:
/plan finished, all sub-plans written)/beads on a planDo NOT use for:
/review)/review-design)/review-prd)At every PAUSE point in this skill, call the AskUserQuestion tool to present structured options to the user. Do not present options as plain markdown text — use the tool. The YAML blocks at each PAUSE point show the exact parameters to pass.
For pattern details and examples: ../_shared/references/stage-gates.md
Fallback: Only if
AskUserQuestionis not available as a tool (check your tool list), fall back to presenting options as markdown text and waiting for freeform response.
Before starting any review, load these shared reference files:
../_shared/references/converge-mode.md../_shared/references/review-finding-taxonomy.mdThese define the CONVERGE mode behavior, MECHANICAL vs DECISION classification, authority hierarchy, PRE_EXISTING severity rules, and finding quality standards shared across all review skills. Skill-specific CONVERGE behavior (wave definitions, authority hierarchy overrides) is documented inline below.
| Mode | When | Depth | Output |
|---|---|---|---|
| BRIEF | Single overview file, simple feature | Structural + design fidelity + PRD coverage | Inline findings summary |
| STANDARD | Overview + sub-plans, typical feature | All 7 phases | Full review report |
| COMPREHENSIVE | Large feature with companion docs | All 7 phases + companion doc audit + cross-reference deep dive | Full review report + alignment findings |
| CONVERGE | Fix all issues until 0 Critical/Major | Selected depth + auto-fix loop | Converged plan + report |
When the user says "converge", "fix all issues", "autoresearch", or selects CONVERGE mode, run the autoresearch convergence loop. CONVERGE can be combined with any review depth:
CONVERGE alone → uses STANDARD depthCONVERGE + COMPREHENSIVE → uses COMPREHENSIVE depth (all phases + companion docs)CONVERGE + BRIEF → uses BRIEF depth (structural + design fidelity only)CONVERGE changes to the normal review flow:
The loop:
Same-session detection: If the plan's creation date matches today AND the conversation contains /plan invocations or plan-writing activity, flag as same-session. Note this in the report. For same-session reviews:
Confidence level: Include in the convergence report:
Authority hierarchy for mechanical fixes:
Technical design (api-surface, data-model) > PRD (FRs, UCs, ACs) > ADRs > Pattern docs > Architecture docs > Plan overview > Sub-plans
Non-greenfield agent prompts: When launching agents to review non-greenfield plans, include ALL of these in the prompt:
Agent context: Agents should receive both the plan files AND the current gap analysis (not just the authority source). This prevents agents from confusing old and new gap analyses.
Agent finding classification: Instruct agents to classify each finding AND provide reasoning. The reviewer validates or reclassifies — agents sometimes classify "missing from design because never designed" as MECHANICAL when it's actually a DECISION.
Agent sub-plan reading: Add to agent prompts: "Before flagging any FR coverage as incomplete, read the full sub-plan body for the covering task(s). The overview table is a summary — the sub-plan is the authority."
Agent false positive rate: Expect 30-40% false positive rate from review agents. Budget time for triage. For plans with ≤3 sub-plans, skip agents and do direct authority source reads + spot-checks instead — the reviewer's own reads are more efficient than filtering agent noise.
Companion doc depth: Scale by plan complexity. For plans with ≤3 sub-plans, structural check is sufficient. For plans with >3 sub-plans, cross-reference companion docs against design test plans and security analysis.
Same-session spot-checks: Increase from 3 to 5 minimum. Target gap analysis claims specifically: (a) does the test infrastructure exist where the plan says, (b) do existing files contain what the gap analysis claims, (c) do "Modify" elements actually have the claimed issues. Same-session generating agents consistently produce stale count/existence errors.
Phase ordering for CONVERGE: Consider running Phase 6 (internal consistency / arithmetic) immediately after Phase 0, not last. Arithmetic errors are the cheapest fixes and most common MECHANICAL findings. Fixing them first reduces cascading corrections.
Test counts single source of truth: The test-scenario-matrix should be the authoritative test count. Overview and sub-plans should reference it ("see test-scenario-matrix.md") instead of stating counts that drift.
Agent finding triage table: Include in the review report: ## Agent Finding Triage with a disposition column (Accepted / False Positive / Reclassified). Makes the review auditable.
Verification Mode phase collapsing: For plans where >90% exists and the gap analysis IS the plan, Phases 2 (design fidelity) and 3 (gap analysis fidelity) collapse into a single check: "does the gap analysis correctly identify what needs to change?" Run them as one phase rather than separately. Phase 2's endpoint/contract verification is redundant when the plan's tasks are verification checklists, not construction blueprints. Without this, agents will produce false positives by assuming greenfield context.
Codebase spot-check: For non-greenfield plans, the gap analysis claims about implementation state are the foundation of the decomposition. A 30-second Grep to verify key claims (e.g., confirm the named class exists, confirm the endpoint route is registered) significantly increases confidence. This is particularly valuable for Phase 3 (Gap Analysis Fidelity).
Token budget: COMPREHENSIVE reviews read the full plan + design + PRD + relevant ADRs/patterns. For plans with 10+ sub-plans, expect 30-50 documents. Models with <200K context may need two-pass approach.
Convergence report: For quick convergences (≤3 rounds, ≤10 findings), use compact format:
{N} findings → {N} fixed in {N} rounds. {N} decisions escalated. Minor: {N} (not fixed).
These are the six sources against which every plan claim is verified. Load them on-demand per phase, not all upfront — this prevents context bloat.
| # | Authority Source | What It Governs | Used In |
|---|---|---|---|
| 1 | /plan skill specification | Plan structure, section requirements, anti-patterns, plan/beads boundary | Phase 1 |
| 2 | Technical design (docs/designs/{feature}/) | Feature decomposition, API surface, data model, design decisions, test plans | Phase 2 |
| 3 | Gap analysis (docs/designs/{feature}/gap-analysis.md or similar) | Gap classifications, scope decisions, migration ordering | Phase 3 |
| 4 | PRD (docs/prd/{feature}/prd.md) | Must-Have FRs, acceptance criteria, use cases, cross-cutting requirements | Phase 4 |
| 5 | Architecture, patterns, ADRs (docs/architecture/, docs/patterns/, docs/adr/) | Binding constraints, conventions, superseded decisions | Phase 5 |
| 6 | The plan itself | Internal consistency across overview, sub-plans, companion docs | Phase 6 |
Step 0.1 — Read All Plan Files:
Read the complete plan:
docs/plans/{feature}/overview.mddocs/plans/{feature}/*.md (excluding overview and companion docs)e2e-test-plan.md, security-hardening-checklist.md, test-scenario-matrix.mdStep 0.2 — Detect Plan Mode:
Determine the plan mode from structure:
overview.md with inline tasks, no sub-plan filesoverview.md + numbered sub-plan filesRecord the mode. Enforce project-level requirements — if the project CLAUDE.md or PRD specifies a required plan mode, flag a mismatch.
BRIEF mode intent check: For BRIEF plans, verify each task's "What" field independently communicates intent without requiring the overview or design doc. An agent receiving only the bead description via br show --json must understand what to build. BRIEF tasks should state the behavior change (not just "implement X per design") and reference relevant design sections by name. Flag BRIEF tasks with unclear independent intent as WARN.
Step 0.3 — Check Gap Analysis Existence:
Look for a gap analysis document:
docs/designs/{feature}/gap-analysis.mddocs/designs/{feature}/gap-analysis/docs/gap-analysis/{feature}/Record whether one exists. Phase 3 is skipped if no gap analysis is found.
Step 0.4 — Read the /plan Skill Spec:
Read the /plan skill specification (this skill's sibling: ../plan/SKILL.md). This is the structural authority for Phase 1. Extract:
Load: /plan SKILL.md (already loaded in Phase 0.4).
Step 1.1 — Overview Document Structure:
Verify the overview contains all required sections from the /plan skill spec:
| Required Section | BRIEF | STANDARD | COMPREHENSIVE |
|---|---|---|---|
| References | Yes | Yes | Yes |
| Decomposition Strategy | Yes | Yes | Yes |
| Cross-Cutting Concerns | Yes | Yes | Yes |
| Task Summary table | Yes | Yes | Yes |
| FR Coverage table | Yes | Yes | Yes |
| UC Coverage table | No | Yes | Yes |
| Design Coverage table | No | Yes | Yes |
| Design Decision Coverage table | No | Yes | Yes |
| Implementation Status (non-greenfield) | No | If applicable | If applicable |
| Dependency Graph | No | Yes | Yes |
| Critical Path | No | Yes | Yes |
| Risk Register | No | No | Yes |
| Testing Summary | No | Yes | Yes |
| Sub-Plans table | No | Yes | Yes |
Flag missing required sections as WARN findings.
Step 1.2 — Sub-Plan Document Structure (STANDARD+):
For each sub-plan, verify required sections:
Verify conditional sections are present when applicable:
Verify mandatory sections:
Flag missing required sections as WARN. Flag missing conditional sections (when clearly applicable) as Minor.
Bead-readiness check: For each sub-plan, verify it could produce a self-contained bead description without re-reading the design: Does it have a clear objective, specific context references, approach guidance, and success/failure criteria? An agent receiving only the derived bead via br show --json must understand what to build. Flag sub-plans that require reading other sub-plans to understand as WARN.
Step 1.3 — Companion Document Compliance (COMPREHENSIVE):
If plan mode is COMPREHENSIVE, verify companion documents exist and contain required structure:
e2e-test-plan.md: Scope, Environment, Smoke Checks, Critical Path Scenariossecurity-hardening-checklist.md: Priority tiers (0/1/2), Exit Criteria (skip if design says "no security implications")test-scenario-matrix.md: Summary metrics, UC-to-test mappingFlag missing COMPREHENSIVE companion docs as WARN.
Step 1.4 — Anti-Pattern Detection:
Check for each anti-pattern defined in the /plan skill spec:
| Anti-Pattern | Detection Signal | Severity |
|---|---|---|
| Horizontal-Only Decomposition | All tasks scoped to a single layer (all DB, then all API, then all UI) with no end-to-end slice | FAIL |
| Deferred Risk | High-risk or integration tasks appear only in late phases | WARN |
| Testing as Phase N | A dedicated "write tests" phase/task with no per-task test expectations. Exception: for non-greenfield plans where existing code has zero tests, a dedicated test task for pre-existing code is legitimate. | WARN |
| 200-Task Plan | Excessive task count relative to feature scope; trivial tasks that should be merged | WARN |
| Plan-as-Design | Sub-plans make architectural decisions not present in the design (new patterns, new entities, new API shapes) | FAIL |
| Copy-Paste Sub-Plans | Large blocks of text duplicated verbatim from design docs instead of referenced | Minor |
| Hollow Sub-Plans | Sub-plans with only prose descriptions — no pseudocode, no contract shapes, no pattern references despite design having produced this detail. Hollow plans produce hollow bead descriptions — agents receive empty execution contracts via br show --json | FAIL |
| Misaligned Decomposition | Sub-plan grouping doesn't mirror the design's feature decomposition structure | WARN |
Step 1.5 — Plan/Beads Boundary Violations:
Verify no sub-plan contains content that belongs in /beads (upper boundary):
Flag upper-boundary violations as Minor (they don't block /beads but indicate confusion about the boundary).
Verify no sub-plan is too thin for /beads to produce a self-contained bead description (lower boundary):
Flag lower-boundary violations as WARN — /beads transforms sub-plans into bead descriptions pushed to br. Hive's BeadsAdapter passes bead.Description directly to executing agents. A sub-plan too thin to stand alone produces a bead too thin to execute.
Load: Technical design documents from docs/designs/{feature}/. Read design.md and all feature subdirectories (features/*/). This phase is the most important — design contradictions in the plan produce wrong code.
Step 2.1 — Feature Decomposition Alignment:
Map the design's feature areas to plan sub-plans:
| Design Feature Area | Plan Sub-Plan | Aligned? |
|--------------------|--------------|---------:|
| features/applications/ | 02-application-feature.md | Yes/No |
| features/role-templates/ | 04-role-template-feature.md | Yes/No |
Flag unmapped design features as FAIL (work that won't get done). Flag plan sub-plans with no design counterpart as FAIL (phantom scope).
Step 2.2 — API Surface & Contract Verification:
For each endpoint in the design's API surface (typically api-surface.md or similar):
Step 2.2b — Field Source Verification:
When a sub-plan says "construct X from Y," "populate X using Y's fields," or "map from Y to X," the reviewer must grep Y's actual type definition in the codebase and confirm every field X requires is present on Y. Do NOT trust the plan's claim — run the grep yourself.
Procedure:
grep -n "class {SourceType}" --include="*.cs" (or equivalent)Example: Sub-plan says "construct WatchSessionInfo from SpawnResult"
SessionId ← SpawnResult.SessionId ✓ (verified — field exists)
ControlPort ← SpawnResult.??? ✗ NOT FOUND on SpawnResult
MaxAgents ← SpawnResult.??? ✗ NOT FOUND on SpawnResult
CreatedAt ← SpawnResult.??? ✗ NOT FOUND on SpawnResult
→ FAIL: 3 of 4 fields not available on claimed source type
Flag plans that hand-wave data sources ("from SpawnResult fields" without listing each field) as FAIL. Flag plans with verified field mismatches as FAIL.
Step 2.3 — Data Model Verification:
Compare the design's data model (entities, columns, constraints, FK behaviours, indexes) against plan tasks:
Step 2.4 — Design Decision Preservation:
For each design decision (chosen approach, rejected alternatives, trade-offs):
Removal impact check: For each task that removes, replaces, or hides existing output/behavior, verify the plan accounts for all information currently provided by the removed behavior. Enumerate what the current behavior provides (error messages, status signals, URLs, warnings) and confirm the plan specifies where each item will be available after the change. Flag removals with unaccounted information loss as WARN.
Step 2.5 — Test Plan Alignment:
Compare the design's per-feature test plans against the plan's Testing Summary and sub-plan success criteria:
Step 2.6 — Companion Doc Fidelity (COMPREHENSIVE):
If companion docs exist, verify them against the design:
Early Termination: If Phase 2 produces 5 or more Critical findings, STOP. Present findings to the user immediately — there is no value in continuing deeper review when the plan fundamentally misrepresents the design. Use the PAUSE described in Phase 7.
Skip this phase if no gap analysis document was found in Phase 0.3. However, check whether the plan's overview embeds a gap analysis (e.g., an Implementation Status table with New/Modify/Exists classifications). If embedded, treat the Implementation Status table as the gap analysis authority source and run Steps 3.1-3.2 against it.
Load: Gap analysis document (standalone or embedded in overview).
Step 3.1 — Gap Coverage:
For every gap classified in the gap analysis:
Step 3.2 — Scope Decision Respect:
Verify the plan respects all scope decisions from the gap analysis:
Flag violations as WARN.
Load: PRD from docs/prd/{feature}/prd.md. Also load use cases from docs/prd/{feature}/use-cases/ and docs/use-cases/ if they exist.
Step 4.1 — Must-Have FR Coverage (Depth Check):
For every Must-Have FR in the PRD:
This is the adversarial step. A plan that maps FR-WIDGET-DELETE to a task titled "Widget CRUD" but whose sub-plan body only covers create and edit has a false coverage claim. The FR Coverage table says "covered" but the implementation won't deliver it.
Flag Must-Have FRs with no task coverage as FAIL. Flag Must-Have FRs with false/shallow coverage as FAIL.
Step 4.2 — Self-Review Claim Verification:
If the plan contains its own FR coverage claims (most plans do, per the /plan skill spec), adversarially verify each claim:
Flag false "Covered" claims as FAIL.
Step 4.3 — Use Case Coverage:
Verify the plan includes a UC Coverage table (new in /plan v3.6). For each use case:
Flag missing UC Coverage table as WARN. Flag use cases with broken execution paths as WARN. Flag Tier 1 UC failure paths with no covering task as FAIL.
Step 4.4 — Design Coverage Matrix:
Verify the plan includes a Design Coverage table (new in /plan v3.6). Cross-reference against the design's api-surface files:
Flag missing Design Coverage table as WARN. Flag design elements with no covering task as FAIL (work that won't get done).
Step 4.4 — Cross-Cutting PRD Compliance:
Check whether the plan addresses PRD cross-cutting requirements:
Flag missing cross-cutting coverage as WARN.
Load on-demand: Only load the specific authority sources relevant to this plan. Do not read all ADRs and pattern docs upfront.
Step 5.1 — ADR Compliance:
Scope relevant ADRs:
docs/adr/README.md (or list docs/adr/) to identify ADR titlesFlag ADR violations as WARN.
Step 5.2 — Pattern Compliance:
Check the plan against established patterns from docs/patterns/:
Flag pattern violations as WARN (they'll cause rework during /execute).
Step 5.3 — Architecture Compliance:
Check the plan against architecture documents from docs/architecture/:
Flag architecture violations as FAIL.
Step 5.4 — Resource Contention:
For tasks that introduce loops, watchers, pollers, or long-running operations that share DI-scoped resources (databases, connections, caches) with other services:
Flag tasks that introduce new consumers of shared stateful resources without specifying instance ownership as FAIL. Flag missing cleanup ordering for shared resources as WARN.
Load: Only the plan files (already loaded from Phase 0).
Step 6.1 — Overview to Sub-Plan Consistency:
Flag inconsistencies as WARN.
Step 6.2 — Cross-Sub-Plan Consistency:
Flag inconsistencies as Minor (confusing but not blocking).
Step 6.2b — Self-Containment Integrity:
Verify no sub-plan relies on implicit context from other sub-plans. Each sub-plan must stand alone as input to /beads. Flag:
These force the executing agent to read multiple bead descriptions when the execution contract model requires each bead be independently sufficient. Flag as Minor (internal consistency issue, but execution contract risk).
Step 6.3 — Dependency Integrity:
Flag circular dependencies as FAIL. Flag invalid references as WARN. Flag incorrect critical path in the overview (Task Summary / Dependency Graph) as FAIL — it directly affects /beads execution ordering. Flag incorrect critical path in prose descriptions as WARN.
Phase 6 requires direct file reads. Do NOT rely on agent summaries for internal consistency checks — dependency graphs, critical path text, and table cross-references need exact text. Read overview.md directly via the Read tool, not via agent summaries.
Critical path verification algorithm: For each task, trace the longest dependency chain ending at it. The critical path is the longest chain ending at the final task. Compare against the plan's stated critical path. This makes the check mechanical rather than relying on mental graph traversal.
Step 6.4 — Naming Consistency:
Flag naming inconsistencies as Minor.
Step 7.1 — Classify Findings:
Every finding gets a severity:
| Severity | Definition | Examples | Autoresearch Mapping |
|---|---|---|---|
| FAIL | Blocks /beads — will produce wrong code or miss requirements | Design contradiction, missing Must-Have FR, phantom scope, circular dependencies | Auto-fixed (MECHANICAL) or escalated (DECISION) |
| WARN | Degrades quality — causes rework or confusion during /execute | Missing plan sections, hollow sub-plans, ADR violations, false FR coverage | Logged, not auto-fixed |
Minor and observational issues are reported inline as notes, not as formal findings. This aligns with review-prd and review-design severity models and ensures CONVERGE mode works consistently across all review skills.
Step 7.2 — Determine Verdict:
| Verdict | Criteria |
|---|---|
| PASS (CLEAN) | 0 FAILs on first review — plan needed no fixes |
| PASS (CONVERGED) | 0 FAILs after CONVERGE rounds — plan was fixed to compliance |
| PASS WITH CONDITIONS | 0 FAILs, WARNs noted as conditions for /beads |
| FAIL | Any FAIL findings remaining after max rounds |
Step 7.3 — Write Review Report:
Save to: ${PROJECT_ROOT}/docs/reviews/review-plan-{feature}-{date}.md
# Plan Review: {Feature Name}
> **Date:** {date}
> **Plan:** `docs/plans/{feature}/overview.md`
> **Mode:** {BRIEF | STANDARD | COMPREHENSIVE}
> **Verdict:** {PASS | PASS WITH CONDITIONS | FAIL}
## Executive Summary
**Findings:** {total} ({N} Critical, {N} Major, {N} Minor, {N} Observation)
{2-3 sentence summary of the plan's overall health and the most important findings.}
### Authority Source Compliance
| Authority Source | Status | FAIL | WARN | Minor |
|-----------------|--------|----------|-------|-------|
| /plan skill spec (structural) | Pass/Fail | {N} | {N} | {N} |
| Technical design (fidelity) | Pass/Fail | {N} | {N} | {N} |
| Gap analysis (scope) | Pass/Fail/N/A | {N} | {N} | {N} |
| PRD (traceability) | Pass/Fail | {N} | {N} | {N} |
| Architecture/patterns/ADRs | Pass/Fail | {N} | {N} | {N} |
| Internal consistency | Pass/Fail | {N} | {N} | {N} |
## Critical Findings
### C1. {Title}
- **Phase:** {which review phase found this}
- **Authority:** {specific document, section, requirement}
- **Plan Location:** {file and section in the plan}
- **Issue:** {description — what the plan says vs what the authority says}
- **Impact:** {what goes wrong if not fixed — why this blocks /beads}
- **Resolution:** {concrete fix}
### C2. ...
## Major Findings
### M1. {Title}
- **Phase:** {which review phase}
- **Authority:** {specific reference}
- **Plan Location:** {file and section}
- **Issue:** {description}
- **Resolution:** {concrete fix}
### M2. ...
## Minor Findings
- **m1.** {one-line description} — {plan location} — {fix}
- **m2.** ...
## Observations
- **o1.** {note for awareness}
- **o2.** ...
---
*Review performed against: /plan skill spec v3.5, design doc, PRD, {N} ADRs, {N} pattern docs*
PAUSE: Present the review summary and verdict, then use a Decision Gate:
AskUserQuestion:
question: "How should we proceed with the plan review findings?"
header: "Verdict"
multiSelect: false
options:
- label: "Fix and re-review"
description: "Address Critical/Major findings, then run /review-plan again."
- label: "Fix Critical only"
description: "Address only Critical findings. Accept Major findings as conditions for /beads."
- label: "Accepted as-is"
description: "Proceed to /beads without changes. Findings noted but not blocking."
- label: "Escalate to design"
description: "Findings indicate design-level issues. Return to /technical-design."
Phases 2 and 4 run first (design fidelity and PRD traceability). These catch the errors that produce wrong code during /beads.
Recommended execution order:
Early termination: If Phase 2 produces 5+ Critical findings, stop after Phase 2. Present findings immediately — continuing deeper review when the plan fundamentally misrepresents the design wastes time and produces noise that obscures the real problems.
AskUserQuestion for ambiguous findings: When a Critical or Major finding has multiple valid resolutions, use AskUserQuestion to let the user choose. Example: "The plan covers FR-WIDGET-DELETE in T03 but the sub-plan body only mentions soft-delete, while the design specifies hard-delete. Should we: (a) update the plan to hard-delete per design, (b) flag as a design change request, (c) accept soft-delete as an intentional deviation?"
Record directly for unambiguous findings: When the authority source clearly contradicts the plan and there's only one valid resolution, record the finding without asking. Example: "The plan's FR Coverage table claims FR-WIDGET-LIST is covered by T02, but T02's sub-plan body only covers widget creation. This is a false coverage claim."
Batch related decisions: When multiple findings have the same resolution pattern (e.g., several sub-plans are missing Failure Criteria sections), present them as a batch rather than asking individually.
Structural Rigidity — Flagging missing exact headings when the content is present under a different name. FAIL if the concern is missing entirely, WARN if addressed under a non-canonical heading. Substance over form — a sub-plan that covers failure criteria in prose is better than one with a perfect "Failure Criteria" heading and no content.
Rubber Stamp — Declaring PASS without reading authority sources. Every verdict must be earned by tracing claims to documents. If you haven't read the design's API surface, you cannot declare API coverage is correct. The skill exists because plans look plausible on the surface — verification requires reading the authority sources.
Template-Only Review — Checking that sections exist without reading their content. A plan can have every required section but contain nonsense in each one. Structural compliance (Phase 1) is necessary but not sufficient — content verification (Phases 2-6) is where real issues are found.
Surface-Level Coverage — Claiming an FR is covered because the FR Coverage table says so, without reading the sub-plan body to verify the task actually addresses the FR. The adversarial stance means verifying the claim, not trusting it. This is the single most common review failure — it's easier to check a table than to read sub-plan bodies.
Inventing Requirements — Flagging the plan for not addressing requirements that don't exist in any authority source. If the PRD doesn't mention audit logging, don't flag the plan for missing audit coverage. Review against what the authority sources say, not what you think they should say. The exception is architecture-level constraints (RLS, authorization) that apply to all features regardless of PRD mention.
Reviewing Unchanged Context — Flagging issues in authority source documents themselves (design flaws, PRD gaps) rather than issues in the plan. This skill reviews the plan. If the design has a flaw, the plan should faithfully reflect the design's flaw — the design flaw is a separate issue for /review-design. The one exception is Phase 2 early termination, where fundamental plan-design misalignment may indicate the plan was written against an outdated design.
| Signal | Meaning | Next Action |
|---|---|---|
| "fix and re-review" | Address findings, run again | Fix plan, then /review-plan |
| "fix critical only" | Accept Major as conditions | Fix Critical findings, proceed to /beads with conditions |
| "accepted as-is" | Proceed despite findings | /beads (findings noted in report) |
| "escalate to design" | Design-level issues found | Return to /technical-design |
When approved: "Plan review complete. Run /beads to create executable work packages."
Skill Version: 2.8 — Version History
Use when the plan is approved, user says "create beads", "beads for...", or plan documents exist.
Use when beads are created (/beads completed), user says "review beads", "check beads", "bead review", or before starting /execute.
Use when design is approved, user says "write the plan", "plan this", "create plan for...", or a design document exists.
Use when beads exist and are ready for implementation. Triggers on "execute", "start implementation", "run beads", or when ready beads exist in the tracker.
Use after /execute completes, user says "review execution", "verify beads", or before creating a PR for executed work.
Use when starting a business feature that needs requirements, when user says "write requirements", "create PRD", "define user stories", or after brainstorm/discovery approval.