iterative-plan-review-with-subagents

name	iterative-plan-review-with-subagents
description	Design pattern for reviewing implementation plans using parallel subagent reviewers with iterative refinement. Use when: (1) designing a complex infrastructure change that needs security + implementation review, (2) creating a migration plan with multiple phases, (3) any plan where missing a critical issue could cause data loss or security exposure. Spawns 2 reviewer agents (security + implementation), collects CRITICAL/IMPORTANT/NIT findings, fixes all CRITICALs, re-runs until zero CRITICALs. Typically converges in 2-3 iterations.
author	Claude Code
version	1.0.0
date	"2026-03-07T00:00:00.000Z"

Iterative Plan Review with Subagents

Problem

Complex infrastructure plans have blind spots — security issues, implementation incompatibilities, race conditions, format mismatches. A single reviewer misses things. Multiple reviewers with different expertise catch more.

Context / Trigger Conditions

• Writing a migration plan (e.g., secrets management, storage migration)
• Designing a multi-phase infrastructure change
• Any plan where a missed issue = downtime, data loss, or security exposure
• User explicitly asks for plan review

Solution

1. Write the plan as a markdown document

Save to docs/plans/YYYY-MM-DD-<topic>.md

2. Spawn 2 reviewer agents in parallel

Agent 1: Security reviewer
- Focus: secret exposure, access control, key management, CI pipeline security
- Classify each finding: CRITICAL / IMPORTANT / NIT

Agent 2: Implementation reviewer
- Focus: format compatibility, race conditions, ordering, tool behavior
- Classify each finding: CRITICAL / IMPORTANT / NIT

Key: give each reviewer specific focus areas and the actual source code to check against.

3. Consolidate and fix CRITICALs

• Merge findings from both reviewers
• Deduplicate (both often find the same issue)
• Fix ALL CRITICALs in the plan document
• Note IMPORTANTs for implementation phase

4. Re-run reviewers on the updated plan

• Same 2 agents, but tell them which CRITICALs were fixed
• Ask them to VERIFY fixes are correct AND find new issues
• Repeat until zero CRITICALs

5. Typical convergence

• v1: 5-6 CRITICALs (format issues, race conditions, missing steps)
• v2: 2-3 CRITICALs (fixes introduced new issues, missed edge cases)
• v3: 0 CRITICALs, only IMPORTANTs remaining

Example Findings from Real Usage (SOPS migration)

Iteration	CRITICALs Found	Examples
v1	6	YAML≠HCL format, git add . commits secrets, no branch protection, parallel race condition
v2	3	SOPS_AGE_KEY_FILE misunderstanding, renew-tls.yml not updated, plan leaks in PR logs
v3	0	All verified fixed. 6 IMPORTANTs noted for implementation.

Verification

• Zero CRITICALs from both reviewers on the final iteration
• IMPORTANTs documented as implementation notes (not blockers)

Notes

• Use sonnet model for reviewers (fast, thorough enough for review)
• Give reviewers actual source code paths to read, not just the plan
• Tell v2+ reviewers what was fixed so they verify, not re-discover
• The final review should say "ONLY report CRITICALs" to avoid noise
• This pattern cost ~$3-5 in API calls but caught issues that would have caused hours of debugging