Plan Mode Review

Iron Law

NO PLAN APPROVAL WITHOUT ALL 5 PHASES REVIEWED — Phase 0 self-review runs first; skipping any phase voids the review

Plan Mode Review

Structured review workflow for non-trivial changes. Covers planning discipline (Phase 0) and 5-phase technical review with severity triage, decision logging, and production readiness gates.

Modes

Ask the user which mode to use:

Reference Files

Load references as needed per phase:

Process

Phase 0: Self-Review Loop (Big Change / Small Change only)

1. Read reference/plan-mode-protocol.md for approval scope and severity rules
2. Read reference/phase0-self-review.md
3. Execute Steps 0.1 through 0.5 in order
4. Do NOT proceed to Phase 1 until Phase 0 gate passes

For Review Only mode: skip Phase 0 but run a lightweight outcome check — ask "Is this still the right thing to build/maintain? Has the original goal changed?"

Phase 0.5: Confidence Gate (Big Change only)

Score the plan across 4 dimensions before allowing implementation to proceed. Each dimension is 0–100. Overall must reach ≥ 80 to proceed (≥ 95 for irreversible changes: migrations, public API contracts, auth architecture).

OVERALL CONFIDENCE: (D1 + D2 + D3 + D4) / 4 = XX%

[≥ 80%] → Proceed to implementation
[60–79%] → Address gaps listed below before proceeding
[< 60%] → STOP — plan needs significant work

Gaps to resolve before proceeding:
- [dimension]: [specific gap — what question couldn't be answered]

Skip for: Small Change and Review Only modes (qualitative Phase 0 gate is sufficient).

For irreversible changes (schema migrations, public API contracts, auth changes): threshold is 95%, not 80%.

Read reference/confidence-gate.md for the full scoring rubric, gap recovery actions, and examples.

Phase 1: Architecture Review

Read reference/review-interaction-protocol.md for visualization and question format requirements.

Evaluate:

• System design and component boundaries
• Dependency graph and coupling
• Data flow patterns and bottlenecks
• Scaling characteristics and single points of failure
• Security architecture (auth, data access, API boundaries)

Generate a Mermaid or ASCII diagram of the current architecture BEFORE discussing issues.

Phase 2: Code Quality Review

Evaluate:

• Code organization and module structure
• DRY violations (be aggressive — per code-standards.md)
• Error handling patterns and missing edge cases
• Technical debt hotspots
• Over-engineering vs under-engineering

For deep review, delegate to the code-reviewer agent with its checklist.

Phase 3: Test Review

Evaluate:

• Coverage gaps (unit, integration, e2e)
• Assertion quality — strong assertions > high coverage percentage
• Missing edge case coverage
• Untested failure modes and error paths

Phase 4: Performance Review

Evaluate:

• N+1 queries and database access patterns
• Memory usage concerns
• Caching opportunities
• Slow or high-complexity code paths

Generate an annotated request/data flow diagram showing timing or complexity.

Phase 5: Production Readiness Review

1. Read reference/production-readiness-gate.md
2. Execute all subsections: blast radius, rollback, dependency health, second-order effects, cost/infra, data migration
3. Verify the production readiness gate checklist before approving

Phase 6: Debate-Based Verification (Optional — Big Change with architecture decision)

When to trigger: Phase 1 (Architecture Review) identified two or more competing valid approaches, OR the change is irreversible (schema migration, public API contract, auth architecture, major refactor).

Skip when: The approach is already decided and uncontested, or the change is scoped to a single service with no structural impact.

3-role structure:

Proponent  →  Presents the chosen approach with supporting evidence
     ↓
Opponent   →  Identifies flaws, raises the strongest case for an alternative
     ↓
Synthesizer →  Weighs both sides, produces a verdict with explicit trade-off reasoning
     ↓
If unresolved → Escalate to human with both positions documented

How to run:

1. Proponent pass — Argue FOR the current plan: what evidence supports it, what constraints it satisfies, what risks it mitigates.
2. Opponent pass — Argue AGAINST: what the alternative approach achieves better, what failure modes the plan has, what the proponent's evidence overlooks.
3. Synthesizer verdict — State which position is stronger and why. Name the deciding factors explicitly. If genuinely tied, list what additional information would break the tie.
4. Escalate if unresolved — If the synthesizer cannot produce a clear verdict, surface both positions to the human with a specific question: "This decision requires human judgement because [reason]."

Output format:

## Debate: [decision being evaluated]

### Proponent
[Strongest case FOR the chosen approach — evidence-backed]

### Opponent
[Strongest case AGAINST — concrete failure scenarios or better alternative]

### Synthesizer Verdict
**Winner:** [Chosen approach / Alternative / Inconclusive]
**Deciding factors:** [What tipped the balance]
**Accepted trade-offs:** [What the winning side gives up]
**Escalate to human:** [Yes/No — if yes, state the specific question]

Relationship to plan-challenger agent: plan-challenger runs one-sided attack (finds holes). Phase 6 debate runs two-sided structured opposition (proponent + opponent + neutral verdict). Use plan-challenger first to find weaknesses, then Phase 6 when two competing valid positions remain after the challenge.

Cross-Skill Delegation

Error Handling

No plan provided: Ask the user to describe the change, paste the plan, or point to a PR/branch.

Scope unclear: Ask which mode (Big Change / Small Change / Review Only) and which phases to include.

Phase 0 gate fails: List which gate items are incomplete. Do NOT proceed — ask the user to resolve.

Cannot verify a claim: Mark as [UNVERIFIED — needs manual check] with the specific command or URL to verify. Never fabricate evidence.