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:

Verdict Condition

CHANGES_REQUESTED

Any blocking issue from any reviewer

APPROVED_WITH_WARNINGS

Warnings but no blockers

APPROVED

No blockers, no warnings

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

• Cost warning - Confirm user wants full review (token-intensive)

• Gather inputs - Find plan, CLAUDE.md, manifest

• Launch reviewers - 4 agents in parallel via Task tool

• Collect results - Wait for all reviewers

• Synthesize - Launch synthesizer with all reports

• Output - JSON to file, summary to user

Common Issues Caught

Issue Type Caught By Example

Hallucinated method Reality User.validate() doesn't exist

Wrong file path Reality src/helpers/ should be lib/utils/

Version mismatch Reality Plan uses pandas v2 API, v1.5 installed

No rollback plan Architecture DB migration without down script

High blast radius Architecture 12 files touched in one PR

Missing tests Quality No test strategy defined

SQL injection Quality Raw f-string SQL query

No error logging Quality Catch block with no logging

Race condition Systems Assumes user exists when order created

Non-idempotent Systems Payment runs twice = double charge

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)