/plan-swarm-review

name: plan-swarm-review
description: |
  Iterative plan review using multisampling + focused decomposition.
  Launches parallel independent agents to find issues that single-pass
  review misses. Up to four bounded rounds: broad, multisample, focused,
  focused-plus-multisample. Use when: "swarm review", "review plan thoroughly",
  "multisample review", "deep plan review", "plan swarming", "stress test
  the plan", or when evidenced cross-component risk warrants deeper plan review.
  Size alone does not require a swarm or another review round. Do NOT use to
  design a multi-agent harness or Generator-Evaluator architecture from scratch;
  use harness-design for that. Ordinary code/diff review routes to deep-review;
  use this skill's code mode only when the user explicitly requests a swarm
  security/bug review of code.
metadata:
  user-invocable: true
  upstream-model-hint: opus
allowed-tools:
  - Read
  - Grep
  - Glob
  - Agent
  - AskUserQuestion
  - TodoWrite
  - Edit
  - Write

Plan Swarm Review

Iterative plan hardening through multisampling and focused decomposition.

Scope and task ownership

The user's current task and selected model govern this review. Audit-only is read-only unless changes are requested. In an already authorized implementation or repair task, apply confirmed in-scope reversible fixes and run their focused causal checks; do not ask again merely because a review round found the problem. An optional deeper review does not block those fixes or the original milestone. Stop expanding review when the current acceptance criteria are sufficiently proved, then return to the owning task. Preserve actual external, deletion, and irreversible boundaries. The four rounds are a bounded menu, not a required loop.

**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 when the user explicitly requests a swarm code review. Merely supplying a diff or asking for ordinary code review routes to `deep-review`. 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** → finish this review scope and return to the owning task; this is not proof that an implementation milestone is finished.

If findings exist: 1. Present findings to user grouped by severity 2. If fixes are already authorized, apply the confirmed scoped corrections and run their focused checks. Otherwise report them within the audit-onl