Plan Review

Plan Review

Overview

Quality gate that validates implementation plans before code execution. Spawns 4 specialized reviewers in parallel, then synthesizes findings into a unified verdict.

Invoke: /review-plan [plan_file] after implementation-planning completes

Position in workflow:

brainstorming → implementation-planning → plan-review → executing-plans

When to Activate

Core Philosophy

Accuracy over speed. This is a quality gate, not a quick check.

• Extra minutes here save days of rework downstream
• Thorough verification prevents production data loss
• A missed hallucination becomes a runtime error
• A missed security issue becomes a breach
• A missed migration rollback becomes unrecoverable data

This is a token-intensive operation. Reserve for high-risk or high-complexity work. For simpler plans, consider a simplified single-reviewer focus.

The Four Reviewers

Plan review spawns 4 specialized agents in parallel, each with a distinct lens:

1. Reality Reviewer

Focus: Does the plan match codebase reality?

• Symbol verification (do referenced methods/classes exist?)
• Path validation (do file paths exist and follow conventions?)
• Version compatibility (do library versions match manifest?)
• Convention alignment (does plan follow CLAUDE.md rules?)

Blocking conditions: Hallucinated symbols, version incompatibilities, convention violations

2. Architecture Reviewer

Focus: Is the structural approach sound?

• Blast radius analysis (how many files touched? weighted by criticality)
• One-way door detection (migrations, deletions, breaking changes)
• Tracer bullet opportunities (>8 sequential steps before integration)
• Dependency vs custom code (reinventing existing libraries)
• Pattern alignment (following established project patterns)

Blocking conditions: One-way doors without rollback strategy

3. Quality Reviewer

Focus: Is the plan production-ready?

• Test strategy (what kind of tests, where, how to run)
• Observability (logging in error paths)
• Edge case coverage (empty inputs, boundaries, failures)
• Security scan (SQL injection, eval(), hardcoded secrets)

Blocking conditions: Missing test strategy, security anti-patterns, no observability

4. Systems Reviewer

Focus: What are the ripple effects?

• Dependency chain analysis (what depends on what's changing?)
• Feedback loop detection (could changes create runaway effects?)
• Failure mode analysis (what if this fails? runs twice? runs out of order?)
• Timing assumptions (implicit ordering dependencies)

Blocking conditions: Critical systemic risks, non-idempotent operations on important data

Verdict Logic

After all 4 reviewers complete, a synthesizer consolidates findings:

Priority scoring: Issues ranked by Severity × Likelihood × Reversibility

Output Format

JSON Report (saved to file)

{
  "verdict": "CHANGES_REQUESTED",
  "summary": "3 blocking issues, 4 warnings",
  "plan_file": "docs/plans/2026-02-03-feature.md",
  "reviewed_at": "2026-02-03T14:30:00Z",
  "blocking_issues": [
    {
      "id": "B1",
      "source": "reality",
      "issue": "Method `Auth.verify()` does not exist",
      "priority_score": 12,
      "resolution": "Use `Auth.check()` or create the method"
    }
  ],
  "warnings": [...],
  "recommendations": [...],
  "reviewer_summaries": {
    "reality": {"status": "ISSUES_FOUND", "blocking": 1},
    "architecture": {"status": "PASS", "blocking": 0},
    "quality": {"status": "ISSUES_FOUND", "blocking": 1},
    "systems": {"status": "PASS", "blocking": 0}
  }
}

Saved to: [plan_directory]/[plan_name].review.json

Human Summary (displayed to user)

## Plan Review: CHANGES_REQUESTED

### Blocking Issues (3) - Must Fix
1. [B1] Hallucinated Method (Reality) - Auth.verify() doesn't exist
2. [B2] SQL Injection Risk (Quality) - Raw SQL in Task 2
3. [B3] Missing Rollback (Architecture) - DB migration needs rollback

### Warnings (4) - Should Fix
...

### Next Steps
Fix blocking issues, then run /review-plan again.

Simplified Mode

For lower-risk plans, /review-plan offers a simplified mode that runs only one reviewer:

Which review focus?
1. Reality - Symbol/path verification
2. Architecture - Complexity, patterns
3. Quality - Testing, observability
4. Systems - Second-order effects

This reduces token usage significantly while still providing focused validation.

Limitations

Symbol extraction is heuristic. Regex patterns may miss:

• Dynamically constructed method calls
• Metaprogramming patterns
• Code references in prose (false positives)

Version checking is API-level. Checks if APIs exist, not behavior changes.

Convention checking requires CLAUDE.md. If project has no CLAUDE.md, convention alignment is skipped.

Plan format matters. Expects plans from implementation-planning skill (v1.0.0+). Other formats may produce incomplete reviews.

Workflow Steps

1. Cost warning - Confirm user wants full review (token-intensive)
2. Gather inputs - Find plan, CLAUDE.md, manifest
3. Launch reviewers - 4 agents in parallel via Task tool
4. Collect results - Wait for all reviewers
5. Synthesize - Launch synthesizer with all reports
6. Output - JSON to file, summary to user

Common Issues Caught

Scope Boundaries

This skill covers:

• Plan validation before execution
• Multi-perspective review (reality, architecture, quality, systems)
• Synthesized verdict with prioritized recommendations

Not covered:

• Plan creation (use implementation-planning)
• Plan execution (use executing-plans)
• Code review post-implementation
• Architecture analysis of existing code (use axiom-system-archaeologist)