review-plan

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.

You can find tasks in ./apex/tasks/ or run with: /apex:review-plan [identifier] Load task file and begin review.

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

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

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

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)

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”)

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]

Summary

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

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