81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
|
---
|
||
|
|
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-07
|
||
|
|
---
|
||
|
|
|
||
|
|
# 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
|