review-plan

Lightweight plan review that catches gaps and errors before implementation commitment.

Three focused lenses:

1. Completeness - Are all required plan artifacts present and substantive?
2. Gap Analysis - What did research find that plan doesn't address?
3. Correctness - Is the plan internally consistent and feasible?

Output goes to chat. User fixes issues inline, then proceeds to implement.

./apex/tasks/[ID].md research, plan chat - **Advisory Only**: No phase changes, no file modifications - **Fast**: Direct analysis, no subagents - **Actionable**: Every gap or error includes what to fix - **Honest**: Call out real problems, don't rubber-stamp - **Flexible**: Works regardless of current phase I'll review the plan for gaps and correctness. Please provide the task identifier.

You can find tasks in ./apex/tasks/ or run with:
/apex:review-plan [identifier]

Load task file and begin review.

1. Read `./apex/tasks/[identifier].md` 2. Note current phase from frontmatter (informational only - don't block) 3. Extract and parse (note any missing sections): - `` - From within `` section - `` - All findings from research phase - `` - All artifacts from plan phase 4. If `` or `` sections are missing/empty, report as finding (don't refuse) 5. Verify file paths mentioned in `` exist using glob/ls Verify all mandatory plan artifacts are present and substantive. Look for these concepts (tag names may vary):

1. Design Rationale - Current state, problem breakdown, hidden complexity, success criteria
2. Tree of Thought - 3 different solution approaches with a winner selected
3. Chain of Draft - Evolution through multiple drafts
4. YAGNI - What's explicitly excluded, complexity budget
5. Patterns - Which patterns are being applied (can be empty)
6. Architecture Decision - Files to change, implementation steps, how to validate
7. Builder Handoff - Clear mission, ordered steps, validation checkpoints
8. Contract Validation - AC coverage confirmation

- [ ] Plan acknowledges the current contract version - [ ] If amendments exist in task-contract, they are acknowledged in plan - [ ] Every AC in task-contract is addressed somewhere in plan ## Completeness Check

Missing Artifacts

• [Artifact name]: Not found or empty
  • Fix: Add required section to plan

Incomplete Artifacts

• [Artifact name]: Missing [specific subsection]
  • Fix: Add [subsection] with [expected content]

Contract Issues

• Version mismatch: Contract v[X] but plan references v[Y]
  • Fix: Update plan to reference current contract version
• Unacknowledged amendment: Amendment not recorded in plan
  • Fix: Acknowledge the amendment in plan

Completeness Score: [N] artifacts present, [N] issues

Find what research discovered that plan doesn't address. **Research Risks vs Plan Mitigations:** - [ ] Every risk identified in research has a mitigation in plan - [ ] High-probability AND high-impact risks have explicit handling - List any unaddressed risks with their probability/impact

Research Security Concerns vs Plan:

• Security concerns from research are addressed in plan OR explicitly excluded
• List any unaddressed security concerns

Pattern Provenance:

• Patterns claimed in plan can be traced to research (pattern library or codebase conventions)
• Trust scores roughly match what research found
• List any patterns that appear fabricated or unsupported

Documentation Drift:

• Docs flagged for update in research are included in plan's files to modify (or noted as intentionally skipped)
• List any documentation that will drift

Research Recommendations vs Chosen Solution:

• Plan's chosen solution aligns with research recommendation (or has justification for divergence)
• List any unexplained divergences

Task Contract Coverage:

• Every AC in task-contract maps to implementation steps
• Non-functional requirements are addressed in validation approach
• List any uncovered ACs or NFRs

Complexity Budget:

• Plan's complexity estimate is reasonable given what research found
• Flag if plan seems significantly over/under-scoped

## Gap Analysis

Unaddressed Risks

• [Risk name] (probability: [H/M/L], impact: [H/M/L]): Research identified [description]. Plan has no mitigation.
  • Fix: Add mitigation to plan's risk section.

Security Gaps

• [Concern]: From research, not addressed in plan.
  • Fix: Add to risks or explicitly exclude with rationale.

Pattern Issues

• [Pattern]: Claimed in plan but can't find source in research.
  • Fix: Remove pattern or trace back to research source.
• [Pattern]: Confidence rating mismatch ([X] in plan vs [Y] in research).
  • Fix: Align confidence rating with research.

Documentation That Will Drift

• [doc path]: Research flagged for update, not in plan's files to modify.
  • Fix: Add to files or note why update not needed.

Uncovered Requirements

• AC-[N]: [Description] - No implementation step addresses this.
  • Fix: Add step to cover this AC.
• NFR [type]: [Constraint] - Not validated.
  • Fix: Add validation for this constraint.

Gap Score: [N] gaps ([N] critical, [N] moderate, [N] minor)

Verify plan is internally consistent and feasible. **Internal Consistency:** - [ ] Chosen solution in summary/metadata matches the winner in Tree of Thought - [ ] Complexity estimate aligns with risks (high risk → expect higher complexity) - [ ] Implementation sequence in architecture decision matches builder handoff - [ ] Risk level matches actual risks identified - List any contradictions

Tree of Thought Validity:

• 3 solutions are genuinely different approaches (not variations of same idea)
• Winner selection has concrete reasoning citing evidence (not "this feels right")
• Pros/cons reference specific findings from research, not hypotheticals

Chain of Draft Evolution:

• Final draft is meaningfully different from first draft (not cosmetic rewording)
• Issues identified in earlier drafts are resolved in later drafts
• Evolution shows actual refinement based on research insights

YAGNI Coherence:

• Excluded features don't contradict task contract in-scope items
• Excluded features aren't required by any AC

Implementation Sequence:

• Steps are in dependency order (foundations before dependents)
• Each step has a concrete validation (command to run, not "verify it works")
• File paths to modify exist (verify via glob)
• New files are clearly marked as new

Validation Quality:

• Automated validation includes actual runnable commands (npm test, pytest, etc.)
• Manual verification has specific steps, not vague checks

Feasibility:

• No circular dependencies in implementation sequence
• Patterns applied at sensible locations (not generic "apply everywhere")
• No magical thinking ("this edge case won't happen")

## Correctness Check

Internal Contradictions

• [Field A] vs [Field B]: [A] says [X] but [B] says [Y]
  • Fix: Reconcile to [recommendation]

Tree of Thought Issues

• Solutions not distinct: [A] and [B] are variations of same approach
  • Fix: Replace [B] with genuinely different architecture
• Weak winner reasoning: Selection based on preference, not evidence
  • Fix: Add specific research findings supporting choice

Implementation Issues

• Step [N]: [Problem - missing validation, wrong order, etc.]
  • Fix: [Specific correction]
• Vague validation gate: "[gate text]" is not testable
  • Fix: Replace with concrete command: [suggested command]

File Path Issues

• [path]: Listed in files-to-modify but does not exist
  • Fix: Correct path or move to files-to-create

Feasibility Concerns

• [Concern]: [Why this might not work]
  • Fix: [How to address]

Correctness Score: [SOUND / MINOR_ISSUES / MAJOR_ISSUES]

# Plan Review: [Task Title]

Summary

Dimension	Status	Issues
Completeness	[✅ Complete / ⚠️ Gaps / ❌ Missing Artifacts]	[N]
Gap Analysis	[✅ Clean / ⚠️ Gaps / ❌ Major Gaps]	[N]
Correctness	[✅ Sound / ⚠️ Minor Issues / ❌ Major Issues]	[N]

Recommendation: [PROCEED / REVISE / RETHINK]

---

Completeness Check

[From step 2]

---

Gap Analysis

[From step 3]

---

Correctness Check

[From step 4]

---

Action Items

Must Fix Before Implement

Issues that will cause implementation to fail or produce wrong results

1. [Issue with specific fix]

Should Address

Issues that won't block but will cause problems later

1. [Issue with specific fix]

Consider

Improvements that would make the plan better

1. [Suggestion]

---

Next Steps

[If PROCEED]: Ready for /apex:implement [identifier]
[If REVISE]: Fix the issues above in this session, then re-run /apex:review-plan [identifier]
[If RETHINK]: Fundamental issues found - consider returning to /apex:plan [identifier] to rework architecture

**Must Fix** (blocks implementation): - Missing mandatory artifacts (completeness) - Unaddressed high-impact risks - Fabricated patterns (no source in research) - Uncovered acceptance criteria - File paths that don't exist (listed as modify, not create) - Internal contradictions (metadata vs content) - Vague validation gates with no concrete commands

Should Address (causes problems later):

• Unaddressed medium-impact risks
• Documentation drift (docs-to-update not in plan)
• Unacknowledged contract amendments
• Weak Tree of Thought (solutions too similar)
• Chain of Draft shows no real evolution
• Trust score mismatches
• NFRs not validated

Consider (improvements):

• Minor inconsistencies in wording
• Complexity budget slightly high
• Could use additional patterns
• Validation could be more thorough

- **PROCEED**: 0 Must Fix items - **REVISE**: 1-3 Must Fix items (fixable in current session) - **RETHINK**: 4+ Must Fix items OR most key artifacts missing OR fundamental architecture problems (wrong solution chosen, contradicts research) - Task file read (regardless of phase) - Missing sections reported as findings, not errors - File existence verified via glob/ls - Completeness check: key artifacts assessed - Gap analysis: risks, security, patterns, docs, ACs, NFRs checked - Correctness check: consistency, validity, feasibility assessed - Classification rubric applied consistently - Clear recommendation with actionable next steps