Plan Swarm Review

Plan Swarm Review

Iterative plan hardening through multisampling and focused decomposition.

Core insight: a single agent misses issues due to attention budget limits. Multiple independent agents reading the same document find different problems (stochastic diversity). Focused decomposition further improves depth per aspect. Iterative fix-then-re-review uncovers issues previously masked by other bugs.

Source: deksden (@deksden_notes) — "Plan Swarming" technique, April 2026. Related: Anthropic Harness Design (Generator-Evaluator), deep-review (parallel competency code review).

Research backing:

• [2502.11027] Sampling diversity in LLM inference — diverse prompts beat identical: +10.8% reasoning, +9.5% code
• [2602.09341] AgentAuditor — reasoning tree audit beats majority voting, recovers 65-82% of minority-correct findings
• [2602.17875] MultiVer — 4 parallel agents hit 82.7% recall on vulnerability detection (beats fine-tuned models)
• [2510.00317] MAVUL — multi-agent vuln detection: +600% vs single-agent
• Anthropic Code Review (Mar 2026) — parallel agents raise substantive findings from 16% to 54%

Modes

This skill works in two modes:

Plan mode (default): review design docs, specs, ADRs, RFCs before implementation. Code mode: review code files for bugs and vulnerabilities. Activated when user passes code files instead of a plan, or says "review code", "find vulnerabilities", "security audit". In code mode, aspects shift from plan-oriented (contracts, completeness) to code-oriented (injection, auth bypass, race conditions, memory).

---

Step 0: Identify the target document

Ask the user which document to review if not obvious from context.

Plan mode: PLAN.md, ADR, spec, design doc, RFC, or any structured document describing what will be built and how.

Code mode: source code files, a module, or a directory. Best for security audits, bug hunts, or pre-release quality checks.

Read the target document(s) fully. Note:
- Total size (lines, sections/files)
- Key components/modules described or implemented
- Interfaces between components
- Data flows and mutations
- External dependencies and trust boundaries

If the target is 2 interacting components | | Data Flow & Migrations | Plan involves data transformation, DB changes, or state migration | | Negative Scenarios | Plan describes user-facing features or distributed systems | | Consistency | Plan is >300 lines or written by multiple authors | | Completeness | Plan references external systems or has phased rollout | | Security & Trust | Plan involves auth, user input, or external APIs | | Dependencies & Order | Plan has >5 implementation steps or parallel workstreams |

Code mode aspects (for bug/vulnerability hunting)

Before launching agents: read references/vulnerability-kb.md for condensed detection heuristics per CWE class. Feed the relevant CWE heuristics into each agent's prompt. Full Vul-RAG entries with code examples: knowledge-vault/docs/security/cwe/.

Based on MultiVer [2602.17875] and VulAgent [2509.11523] patterns:

| Aspect | What to trace | |---|---| | Injection & Input Validation | SQL/NoSQL/command/LDAP injection, XSS, path traversal, template injection | | Auth & Access Control | Auth bypass, privilege escalation, IDOR, missing authorization checks | | Concurrency & State | Race conditions, TOCTOU, deadlocks, shared mutable state, atomicity violations | | Memory & Resources | Buffer overflows, use-after-free, resource leaks, unbounded allocations | | Error Handling & Recovery | Swallowed errors, info leakage in errors, incomplete cleanup, missing rollback | | Cryptography & Secrets | Weak algorithms, hardcoded secrets, improper random, timing attacks | | Business Logic | State machine violations, numeric overflow in prices, missing validation of business rules |

Present selected aspects to user: "I'll focus review on these {N} aspects: ..."

Step 3b: Launch focused agents

For each aspect, launch ONE Agent with a FOCUSED prompt:

You are reviewing a plan document with a SINGLE focus: {ASPECT_NAME}.
Ignore everything outside your focus area — other reviewers handle those.

## Your focus: {ASPECT_NAME}
{ASPECT_DESCRIPTION — 2-3 sentences explaining what to look for}

## Plan to review
{reference the plan document path — the latest version with all prior fixes}

Read the ENTIRE plan but analyze ONLY through the lens of {ASPECT_NAME}.
Go deep: trace every {aspect-relevant thing} end-to-end. Check that every
scenario is complete, every interface is specified, every edge case is handled.

## Output format
FINDING: {one-line description}
SECTION: {which section}
SEVERITY: HIGH | MEDIUM | LOW
ASPECT: {ASPECT_NAME}
EVIDENCE: {quote, max 2 lines}
FIX: {concrete change}

If clean — output: "NO_FINDINGS — {ASPECT_NAME} review clean."

Launch ALL aspect agents in a SINGLE message (parallel).

After Round 3

Same dedup + synthesis. Present focused report.

Stop criteria: 0 high + Round {N+1} | STOP - plan is clean ====================================================

---

## Step 5: Final summary

After the last round (wherever the process stops):

==================================================== PLAN SWARM REVIEW COMPLETE ==================================================== Rounds executed: {N} Total agents launched: {count} Total findings: {count} ({fixed} fixed, {deferred} deferred)

By severity: HIGH: {count found} -> {count fixed} MEDIUM: {count found} -> {count fixed} LOW: {count found} -> {count fixed}

Round breakdown: R1 (broad): {findingscount} findings R2 (multisample): {findingscount} findings R3 (focused): {findingscount} findings R4 (focus+multi): {findingscount} findings

VERDICT: {HARDENED | IMPROVED | NEEDS_REWORK} ====================================================

Verdicts:
- **HARDENED** — all high fixed, <=3 medium remaining → safe to implement
- **IMPROVED** — significant issues found and fixed, some medium deferred
- **NEEDS_REWORK** — structural issues remain, plan needs major revision

---

## Gotchas

- **Token cost**: Round 4 with 7 aspects x 3 samples = 21 agent launches.
  Always confirm with user before expensive rounds.
- **Plan mutations between rounds**: after applying fixes, the plan changes.
  Each new round MUST read the UPDATED plan, not the original.
  Reference the file path, not inline text, so agents always read current version.
- **Subagent depth**: Agent tool subagents cannot launch sub-subagents.
  Each reviewer runs Read/Grep/Glob inline. This is fine for plan review
  (the plan is typically 1-3 files).
- **Diminishing returns**: Round 4 typically finds 1-3 medium issues.
  If Round 3 found 0 high, skip Round 4.
- **False positives**: multisampling creates duplicates. The dedup step (after
  each round) is critical — don't count the same issue from 3 agents as 3 issues.
- **Not for code review**: this skill reviews PLANS. For code review use
  /deep-review (competency-based parallel code review).

## When to use this vs other review skills

| Scenario | Use |
|---|---|
| Quick architecture check | /plan-eng-review |
| CEO-level scope challenge | /plan-ceo-review |
| Design/UX review | /plan-design-review |
| Code diff review (pre-merge) | /review or /deep-review |
| **Thorough plan hardening before implementation** | **/plan-swarm-review** (plan mode) |
| **Plan with many interacting components** | **/plan-swarm-review** (plan mode) |
| **High-stakes plan (infra, security, payments)** | **/plan-swarm-review** (plan mode) |
| **Security audit of a module/codebase** | **/plan-swarm-review** (code mode) |
| **Pre-release vulnerability hunt** | **/plan-swarm-review** (code mode) |
| **Bug hunt when "something is wrong but tests pass"** | **/plan-swarm-review** (code mode) |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AnastasiyaW](https://github.com/AnastasiyaW)
- **Source:** [AnastasiyaW/claude-code-config](https://github.com/AnastasiyaW/claude-code-config)
- **License:** MIT

Install and usage instructions live in the source repository linked above.