/review-swarm

name: review-swarm
description: >-
  Reviews a diff with parallel local specialists, verifies each finding, and
  ranks the survivors as Blockers / Should-fix / Nits.
when_to_use: >-
  Use unasked after a non-trivial implementation or when asked to review a
  diff, branch, or PR. Also on "review-swarm", "swarm review", "deep
  review". Security is the whole ask: don't invoke this or spawn reviewers,
  even on "swarm". Open the final answer by naming /security-review, then
  run or recommend it; a one-pass review of your own may follow that line
  but never replaces it. Trivial diff (docs, rename, one-liner): read it
  once or point to /code-review; spawn nothing, even when named. Not for a
  fix request or when /code-review is named.
argument-hint: "[optional: 'staged' | 'branch' | a path]"
effort: high
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git merge-base *) Bash(git log *)
disallowed-tools: Edit Write NotebookEdit

Review Swarm

!`git status --short 2>&1; echo "--- diff --stat (working tree)"; git diff --stat 2>&1; true`

The block above is the working tree's dirty state and diff shape, captured before you see the rest of this skill — raw command output, not analysis.

Review the working changes with a panel of specialists in parallel, then keep only the findings that survive scrutiny. The subagents are local and spend the user's own tokens: seven sonnet reviewers (six when there is no spec to check against), then opus verifiers for the non-trivial findings, 15 agents at most.

Proactive use

If the user asks to review, check, or assess changes — or you've just finished a non-trivial implementation and a PR is next — invoke this without being asked: announce in one line ("Running review-swarm on <scope>") and proceed. Never ask permission to run the skill.

Scope

Default: working tree vs the default branch. `staged` → `git diff --staged`; `branch` → vs merge-base with main; a path → limit to it. Read the changed hunks and enough surrounding code to judge them.

**Size guard:** over ~40 changed files or ~2000 changed lines, don't swarm the whole thing — split by area and say which slice you reviewed, or ask which slice matters. A swarm that overruns its context reports confidently on code it never read.

**Spec source:** find what the change was meant to do, in this order: the `TODO_WORKFLOW.md` row or design-doc section it implements, the PR or issue description, a spec path the user gave, the request as the user stated it in this conversation. Read it before spawning. If there is none, the Spec reviewer does not spawn and the report says "Spec: no spec found".

Agent budget

At most **15 agents** per review: up to 7 reviewers and up to 8 verifiers.

Before the first spawn, state the plan in one line, so the user sees the spend before it happens:

Plan: <R> reviewers (sonnet) + up to <V> verifiers (opus), cap 15

When the reviewers are back, before the verifiers spawn, state the second half:

Verifying <n> findings with <v> verifiers

More than 8 findings to verify: give one verifier several claims that share a file or a root cause, highest severity first. Each claim still gets its own verdict. Never spawn a 16th agent. A finding the budget left unverified goes on the report's Not reviewed line and is not ranked.

Reviewers

Spawn the specialists below with the Agent tool, **all in one message** so they run concurrently, each with `model: sonnet`. That message opens with the `Plan:` line from Agent budget; the spawns follow it. Give each the diff plus the files it needs and its single lens. Each returns findings as: `severity · file:line · what · why · suggested fix`.

• **Correctness** — logic errors, edge cases, null/empty, off-by-one, concurrency/races.
• **Security & trust boundaries** — authz/authn (JWT), input validation at boundaries, injection, IDOR, leaked secrets.
• **Data & performance** — N+1 (JPA/Hibernate, SQLAlchemy), missing indexes, unbounded queries, transaction scope, lazy-load traps.
• **Architecture & altitude** — does it fit the domain model? are invariants enforced at the core? wrong layer, leaky abstraction.
• **Simplicity (ponytail lens)** — over-engineering, premature abstraction, dead code, a stdlib/native one-liner that replaces the change.
• **Tests & failure paths** — non-trivial logic with no test, untested failure paths, error handling that could lose data.
• **Spec** — the diff against the spec source, and nothing else. Give it the spec text along with the diff. It returns three kinds of finding: *missing* (the spec asks for it, the diff lacks it), *scope creep* (the diff does it, the spec never asked), *wrong* (both have it and they disagree). Each one quotes the spec line it rests on, in place of a severity.

Verification

For each non-trivial finding, spawn a verifier with `model: opus` that tries to *refute* it. The verifier receives the claim and the code, and nothing else from the reviewer. Write its prompt to this recipe:

Claim: <the finding as one checkable sentence> at <file:line>
Code: <the hunk, plus the paths to read to judge the claim>
Task: try to refute the claim. Is it real, reproducible, not already handled elsewhere?
Return: holds | refuted | cannot tell, with the evidence (a file:line or command output). For "cannot tell", name the one fact that would settle it.

The reviewer's reasoning, its severity and its suggested fix stay out of that prompt: a verifier handed the argument tends to agree with it. For a Spec finding, the quoted spec line is part of the claim. You assign severity after the verdicts are in.

What each verdict does:

• **holds** → the finding is ranked in the report.
• **refuted** → dropped.
• **cannot tell** → it goes to Needs validation if the verifier named the missing fact (a column's type, a table's size, whether a gateway already enforces auth). With no nameable fact, drop it.

Never report a finding that has not been through the verifier pass.