---
name: plan-swarm-review
description: |
  Iterative plan review using multisampling + focused decomposition.
  Launches parallel independent agents to find issues that single-pass
  review misses. 4 escalating rounds: broad -> multisample -> focused ->
  focused+multisample. Use when: "swarm review", "review plan thoroughly",
  "multisample review", "deep plan review", "plan swarming", "stress test
  the plan", or before implementing any plan >500 lines or with >3
  interacting components. Also use proactively when a large plan is about
  to be implemented — catch issues before code, not after.
user-invocable: true
model: opus
allowed-tools:
  - Read
  - Grep
  - Glob
  - Agent
  - AskUserQuestion
  - TodoWrite
  - Edit
  - Write
---

# 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 <100 lines with 1-2 simple components, suggest a single-pass
review instead — swarming is overkill for small targets.

---

## Step 1: ROUND 1 — Broad Review (single agent)

**Purpose**: catch obvious issues before spending tokens on multisampling.

Launch ONE Agent with this prompt:

```
You are a senior architect reviewing a plan document before implementation.
Your goal: find issues that would cause bugs, rework, or confusion during
implementation.

## Plan to review
{paste or reference the plan document path}

Read the entire plan. Then check for:

1. CONTRACTS — are interfaces between components fully specified?
   Types, error codes, required vs optional fields, versioning.
2. DATA FLOW — is data transformation described end-to-end?
   What happens at each boundary? Backward compatibility?
3. NEGATIVE SCENARIOS — what happens when things fail?
   Timeouts, partial failures, invalid input, race conditions.
4. CONSISTENCY — do different sections contradict each other?
   Same entity described differently in two places?
5. COMPLETENESS — are there gaps? Steps that say "TBD" or "later"?
   Scenarios mentioned but not covered?
6. DEPENDENCIES — is implementation order clear?
   Are blocking dependencies identified? Circular deps?
7. AMBIGUITY — could two engineers read a section and implement
   it differently? Vague terms like "handle appropriately"?

## Output format
For EACH finding:

FINDING: {one-line description}
SECTION: {which section of the plan}
SEVERITY: HIGH | MEDIUM | LOW
EVIDENCE: {quote the problematic text, max 2 lines}
FIX: {concrete change to the plan text}

If the plan is clean — output: "NO_FINDINGS — plan review clean."
Do NOT pad with praise. Only problems.
```

### After Round 1

Collect findings. If **0 findings** → plan is clean, congratulate user, stop.

If findings exist:
1. Present findings to user grouped by severity
2. Ask: "Apply these fixes and continue to Round 2 (multisampling)?"
3. If user approves fixes → apply them to the plan document
4. If user says stop → stop

---

## Step 2: ROUND 2 — Diverse Multisampling (N parallel agents, varied perspectives)

**Purpose**: stochastic diversity catches what one pass missed.

**IMPORTANT**: do NOT use identical prompts for all agents. Research [2502.11027]
shows identical prompts produce correlated errors — agents "cluster" on the same
issues and miss the same blind spots. Instead, give each agent a DIFFERENT
perspective while reviewing the same document.

Launch **3 agents in parallel** (or 5 for critical plans), each with a
**different reviewer persona**:

**CRITICAL**: launch all agents in a SINGLE message (parallel tool calls).
Each agent has isolated context — no cross-contamination.

### Plan mode perspectives

| Agent | Persona | Focus bias |
|---|---|---|
| 1 | **Skeptical implementer** | "I have to code this tomorrow — what's unclear, contradictory, or impossible?" |
| 2 | **Security auditor** | "Where are the trust boundaries? What happens with malicious input?" |
| 3 | **QA engineer** | "How do I test this? What edge cases aren't covered? What breaks at scale?" |
| 4 | **New team member** | "I just joined — what terms are undefined? What implicit knowledge is required?" |
| 5 | **Ops/SRE** | "What fails at 3am? What's the rollback plan? What's unmonitored?" |

### Code mode perspectives

| Agent | Persona | Focus bias |
|---|---|---|
| 1 | **Attacker** | "How do I exploit this? Injection, auth bypass, privilege escalation?" |
| 2 | **Concurrency specialist** | "What races, deadlocks, or ordering issues exist?" |
| 3 | **Performance engineer** | "What's O(n^2)? What allocates unbounded memory? What blocks the event loop?" |
| 4 | **Error recovery auditor** | "What happens when X fails? Is cleanup correct? Are resources leaked?" |
| 5 | **Integration tester** | "Do contracts match? Are types compatible? What breaks at boundaries?" |

```
You are a {PERSONA} reviewing {plan/code} before implementation/deployment.
Your perspective: {FOCUS_BIAS}

Review the ENTIRE document through your specific lens.
{same checklist and output format as Round 1}
```

### After Round 2

1. **Deduplicate**: group findings by section + issue type. When multiple
   agents find the same issue → mark as HIGH CONFIDENCE (consensus).
2. **Preserve minority findings**: a finding from only 1 of 5 agents is
   NOT automatically low-value. Research [2602.09341] shows minority-correct
   findings are often the most valuable — non-obvious bugs that only one
   perspective catches. Flag these as UNIQUE CATCH, do not discard.
3. **Synthesize**: produce merged report. Separate consensus vs unique catches.
4. Present to user with round report format (see Output Format below).
5. Ask: "Apply fixes and continue to Round 3 (focused review)?"

**Stop criteria**: if Round 2 found 0 high + <=2 medium → STOP. Plan is solid.

---

## Step 3: ROUND 3 — Focused Review (decompose into aspects)

**Purpose**: narrow scope = deeper analysis per aspect.

### Step 3a: Determine focus aspects

Based on the target content, select 3-7 aspects.

### Plan mode aspects

| Aspect | When to include |
|---|---|
| **Contracts & Interfaces** | Plan describes >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 + <=2 medium → STOP. Otherwise ask about Round 4.

---

## Step 4: ROUND 4 — Focused + Multisampling (optional, expensive)

**Purpose**: maximum depth. Only for critical plans where Round 3 still found high-severity issues.

**Gate**: ask user explicitly: "Round 3 still found {N} high-severity issues.
Round 4 will launch {aspects x 2-3} agents (~{estimate} tokens). Continue?"

For each aspect from Round 3 that had findings, launch **2-3 agents** with
the same focused prompt. Same parallel launch pattern.

### After Round 4

Final synthesis. At this depth, the plan should be clean.
If still finding high-severity issues → the plan likely needs structural
rework, not just polish. Tell the user.

---

## Output Format (used after each round)

```
====================================================
  ROUND {N}: {BROAD | MULTISAMPLE | FOCUSED | FOCUSED+MULTISAMPLE}
  Agents: {count}  |  New findings: {count}  |  Dupes removed: {count}
====================================================

-- HIGH ({count}) ------------------------------------
  1. [{aspect}] {description}
     Section: {section reference}
     Evidence: "{quoted text}"
     Fix: {concrete change}
     Confidence: {HIGH if found by multiple agents, MEDIUM otherwise}

-- MEDIUM ({count}) ----------------------------------
  2. [{aspect}] {description}
     ...

-- LOW ({count}) -------------------------------------
  3. ...

====================================================
  CUMULATIVE: {total_high} high / {total_medium} medium / {total_low} low
  RECOMMENDATION: CONTINUE -> 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):       {findings_count} findings
    R2 (multisample): {findings_count} findings
    R3 (focused):     {findings_count} findings
    R4 (focus+multi): {findings_count} 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) |
