Review Swarm
Review the working changes with a panel of specialists in parallel, then keep
only the findings that survive scrutiny. Free and local (Claude subagents).
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 ") and proceed.
Never ask permission to run the skill.
Steps
- Scope the diff. 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.
- Fan out specialists — in parallel. Spawn the reviewers below with the
Agent tool, all in one message so they run concurrently. 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.
- Adversarially verify. For each non-trivial finding, spawn a verifier that
tries to refute it: is it real, reproducible, not already handled
elsewhere? Drop findings that don't survive. Default to dropping when
uncertain.
- Synthesize. Dedup overlaps, then rank: Blockers → Should-fix → Nits,
each with file:line and a one-line fix. Close with a short "what's solid".
Rules
- Every finding cites a real
file:line from the diff. No speculative "you
might consider" padding.
- A dimension with nothing to flag gets one line ("Security: no issues"), not a
manufactured nit.
- Don't fix here — this is review. Offer to hand the ranked list to an
implementer (or to
/code-review --fix) if the user wants changes applied.
When not to use
- A trivial diff (docs, rename, one-liner) — a single-pass read or plain
/code-review covers it; a swarm is overkill.
- The ask is "fix it", not "review it" — implement, then swarm the result.
Hand-offs
- Architecture findings that contradict the design docs →
architect audit.
- The diff touches UI, forms, or markup → hand those hunks to
ux-designer
for the UX/a11y read; this swarm judges correctness, not interface quality.
- Simplicity findings the user accepts →
ponytail the fix.
- Heavyweight cloud pass wanted →
/code-review ultra.
Relationship to built-ins
This is the local, free, your-stack-tailored swarm. For the heavyweight
cloud version, /code-review ultra runs specialists in the cloud; plain
/code-review is a single-pass diff review. Reach for this skill when you want
parallel local specialists with adversarial verification and no cloud round
trip.
Done when
The user has a short, ranked, evidence-backed list where every item is a real,
verified problem in the diff — and knows what's clean.
Global rules
Apply on every run — canonical home ~/.claude/CLAUDE.md:
- Ground everything. Only what's given or verified; never invent files, APIs, or facts. Unknown → say "I don't know" or state the assumption.
- No tokenmaxing. Lead with the answer; keep an output budget; no filler, no restating the question.
- Agent discipline. Read before you edit; small reversible changes; ask when blocked, don't guess; report failures honestly.
- Commits are the user's alone. Author = the user; never add an AI co-author or
Co-Authored-By/credit line, and don't mention AI in commit messages.
1---2name: review-swarm3description: Local, free, multi-specialist review of a diff: parallel Claude subagents (correctness, security/trust boundaries, data/perf, architecture-altitude, ponytail-simplicity, tests/failure paths), adversarial verification, dedup, ranked file:line report. Use proactively when asked to review, check, or assess a diff, branch, or PR — and after any non-trivial implementation, before the PR. Also on "review-swarm", "swarm review", "deep review". Not for trivial diffs, not when asked to fix rather than review, not when security alone is the whole ask (built-in "security-review"), and not when "/code-review" is named explicitly.4---56# Review Swarm78Review the working changes with a panel of specialists in parallel, then keep9only the findings that survive scrutiny. Free and local (Claude subagents).1011## Proactive use1213If the user asks to review, check, or assess changes — or you've just finished14a non-trivial implementation and a PR is next — invoke this without being15asked: announce in one line ("Running review-swarm on <scope>") and proceed.16Never ask permission to run the skill.1718## Steps19201. **Scope the diff.** Default: working tree vs the default branch. `staged` →21 `git diff --staged`; `branch` → vs merge-base with main; a path → limit to22 it. Read the changed hunks and enough surrounding code to judge them.23 **Size guard:** over ~40 changed files or ~2000 changed lines, don't swarm24 the whole thing — split by area and say which slice you reviewed, or ask25 which slice matters. A swarm that overruns its context reports confidently26 on code it never read.272. **Fan out specialists — in parallel.** Spawn the reviewers below with the28 Agent tool, **all in one message** so they run concurrently. Give each the29 diff plus the files it needs and its single lens. Each returns findings as:30 `severity · file:line · what · why · suggested fix`.31 - **Correctness** — logic errors, edge cases, null/empty, off-by-one,32 concurrency/races.33 - **Security & trust boundaries** — authz/authn (JWT), input validation at34 boundaries, injection, IDOR, leaked secrets.35 - **Data & performance** — N+1 (JPA/Hibernate, SQLAlchemy), missing indexes,36 unbounded queries, transaction scope, lazy-load traps.37 - **Architecture & altitude** — does it fit the domain model? are invariants38 enforced at the core? wrong layer, leaky abstraction.39 - **Simplicity (ponytail lens)** — over-engineering, premature abstraction,40 dead code, a stdlib/native one-liner that replaces the change.41 - **Tests & failure paths** — non-trivial logic with no test, untested42 failure paths, error handling that could lose data.433. **Adversarially verify.** For each non-trivial finding, spawn a verifier that44 tries to *refute* it: is it real, reproducible, not already handled45 elsewhere? Drop findings that don't survive. Default to dropping when46 uncertain.474. **Synthesize.** Dedup overlaps, then rank: **Blockers → Should-fix → Nits**,48 each with file:line and a one-line fix. Close with a short "what's solid".4950## Rules5152- Every finding cites a real `file:line` from the diff. No speculative "you53 might consider" padding.54- A dimension with nothing to flag gets one line ("Security: no issues"), not a55 manufactured nit.56- Don't fix here — this is review. Offer to hand the ranked list to an57 implementer (or to `/code-review --fix`) if the user wants changes applied.5859## When not to use6061- A trivial diff (docs, rename, one-liner) — a single-pass read or plain62 `/code-review` covers it; a swarm is overkill.63- The ask is "fix it", not "review it" — implement, then swarm the result.6465## Hand-offs6667- Architecture findings that contradict the design docs → `architect audit`.68- The diff touches UI, forms, or markup → hand those hunks to `ux-designer`69 for the UX/a11y read; this swarm judges correctness, not interface quality.70- Simplicity findings the user accepts → `ponytail` the fix.71- Heavyweight cloud pass wanted → `/code-review ultra`.7273## Relationship to built-ins7475This is the **local, free, your-stack-tailored** swarm. For the heavyweight76cloud version, `/code-review ultra` runs specialists in the cloud; plain77`/code-review` is a single-pass diff review. Reach for this skill when you want78parallel local specialists with adversarial verification and no cloud round79trip.8081## Done when8283The user has a short, ranked, evidence-backed list where every item is a real,84verified problem in the diff — and knows what's clean.8586## Global rules8788Apply on every run — canonical home `~/.claude/CLAUDE.md`:89- **Ground everything.** Only what's given or verified; never invent files, APIs, or facts. Unknown → say "I don't know" or state the assumption.90- **No tokenmaxing.** Lead with the answer; keep an output budget; no filler, no restating the question.91- **Agent discipline.** Read before you edit; small reversible changes; ask when blocked, don't guess; report failures honestly.92- **Commits are the user's alone.** Author = the user; never add an AI co-author or `Co-Authored-By`/credit line, and don't mention AI in commit messages.
alonbaron