parallel-audit

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.