| name | parallel-audit |
| description | Runs a broad, multi-dimension codebase audit by fanning out parallel read-only subagents (one per dimension x file-area), independently confirms their findings, then groups the survivors into a parallelizable multi-PR fix plan and self-critiques it before delivery. Activate when the user asks to "find dozens of issues", "audit the codebase", "find security/ robustness/testing/UX deficiencies", "use subagents to audit and confirm", "find bugs and missed opportunities", or "make a plan to fix all of these in parallel across multiple PRs". Distinct from peer-review (which reviews a pending diff) and security-review (single-pass, current branch): this audits the WHOLE codebase along several axes at once and ends in a vetted fix plan, not edits.
|
Parallel Audit Skill
The "fan out, confirm, plan, critique" pattern for a wide audit of an existing codebase along
multiple quality axes (security, robustness, real-vs-stubbed test coverage, UX, missed
opportunities). Output is an audit report + a multi-PR parallel fix plan + a critique of that
plan — no code changes beyond scaffolding the user explicitly asks for. One agent reading a large
repo serially is slow and shallow; N agents each owning one dimension x area read deep, and an
independent confirmation pass keeps cheap-but-wrong findings out of the plan.
When to use
- Breadth ("dozens", "be creative", "across the whole thing"), not a review of one diff, and the
deliverable is a plan rather than immediate edits.
- Not this: a pending diff before a PR →
peer-review/code-review; a single-pass look at the
current branch → security-review; a trivial single-file question → just read the file.
Workflow
1. Map the territory (main session, fast)
Get a lay of the land so agent scopes are disjoint: directory tree, file-type counts, key
subsystems. Skim CLAUDE.md/CONTRIBUTING.md/SECURITY.md — their stated invariants ("fail
closed", "post-condition not exit code", "host code runs on BSD too") become the lenses you hand
each agent. An audit that checks the project's own doctrine finds violations of it; a generic audit
re-discovers lint.
2. Fan out — one agent per (dimension x area), all in ONE message
Pick axes from the request (typical: security, robustness/error-handling, e2e-test realness, UX/DX,
supply-chain, config-SSOT/CI). Give each general-purpose agent a non-overlapping file list and
launch them concurrently (multiple Agent calls in one response). They are read-only — forbid
edits; read-only audit of .claude//sandbox-policy/ is fine, but never delegate edits there
(write guards block them silently — keep those for the main session later).
Each agent prompt MUST demand, per finding:
TITLE · FILE:LINE (exact) · SEVERITY · EVIDENCE (quote 1-5 real lines) · WHY IT'S A DEFECT
(a concrete failure: specific input → wrong/leaked outcome) · SUGGESTED FIX (one line). And MUST
instruct:
- Ground every finding in real lines read — never speculate. Skip anything you can't quote.
- Self-flag non-findings: state what you checked and found correct. This honesty signal tells
you which agents to trust — an honest self-flagger earns lighter scrutiny in step 4.
- Rank by severity; aim for a target count (e.g. 6-12) so they prioritize over dumping noise.
3. Survive the rate limit — resume, don't restart
A big fan-out often trips a transient rate limit; an agent returns 0 tokens after having already
done real reading. Resume it with SendMessage to its agentId ("continue where you left off
and emit your final findings") to reuse its accumulated context instead of paying for the reads
again. Fully restart only an agent that died before doing any work (≈≤3 tool calls).
4. Confirm — independently, at least the high-severity items
Do not rubber-stamp. For every high/critical finding (and a sample of the rest), open the cited
file at the cited lines yourself and check the claim holds. Watch for: off-by-a-few line numbers,
a comment that already addresses the concern, a guard one function up the agent missed, severity
inflation. Drop or downgrade anything that doesn't survive your read; record "confirmed by
independent read" per kept finding. For very large audits this pass can itself be a second fan-out
of code-reviewer agents, each adversarially trying to refute one finding — keep the survivors.
5. Dedupe and cluster into parallel-safe PRs
Merge duplicates across agents (the same bug often surfaces from two lenses). Group survivors by the
disjoint-file-area rule: two PRs can land in parallel only if they touch non-overlapping
files — that is the real constraint, not theme. Natural grouping: one PR per subsystem (firewall,
monitor, redaction, lifecycle, …), bundling that subsystem's findings. Note cross-PR ordering only
where a real dependency exists (e.g. an SSOT change others build on). For each PR: scope, the
findings it closes, the test that would have caught the class (assert the invariant, not today's
symptom), and a rough size.
6. Critique the plan, then deliver
Attack it first: are any "parallel" PRs actually file-conflicting? Is a "high" really reachable, or
gated behind an opt-in/off-by-default flag (lower it)? Does any fix need a design decision (flag it
in the delivered plan with a recommended default — never stop mid-audit to ask)? Any findings with
no good test? Is the PR count realistic, or should some merge? Deliver the plan with this
critique attached — the user asked to see it. Plan delivery is the ONE moment to batch every open
question; concentrate them there.
7. Executing the plan (when asked)
The whole PR list is in scope — work through every PR without checkpointing; never ask "should I
move on to the next PR?" (the answer is always yes). Any question belongs in the batch delivered
with the plan (step 6), before the first PR. A design choice that surfaces only mid-implementation
gets a sensible default and a ## Decisions made entry in that PR's description (what came up, the
default chosen, what would change under the alternative) — logged for async review, not asked.
Maintain a PR-queue checklist and tick each off as it opens, so progress is supervisable at a glance.
