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

Codifies 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). The output is an audit report + a multi-PR parallel fix plan + a critique of that plan — the skill itself ships no code changes beyond optional scaffolding the user explicitly asks for. It exists because 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 the cheap-but-wrong findings out of the plan.

When to use

• The user wants breadth ("dozens and dozens", "be creative", "across the whole thing") rather than a review of one diff.
• The codebase is large enough that serial reading would be shallow (many files / subsystems).
• The deliverable is a plan, not immediate edits.

When NOT to use

• Reviewing a pending diff before a PR → peer-review / code-review.
• A single-pass security look at the current branch → security-review.
• Trivial / single-file questions — just read the file.

Workflow

1. Map the territory (main session, fast)

Before spawning anything, get a lay of the land so agent scopes are disjoint: directory tree, file-type counts, the key subsystems. Skim any 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 knows 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 agent a non-overlapping file list so they don't collide or duplicate. Launch them concurrently (multiple Agent calls in a single response). Use general-purpose (full read tools); they must be read-only — forbid edits.

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 you read — do NOT speculate. Skip anything you can't quote.
• Self-flag non-findings: if you checked something and it's actually correct, say so explicitly. (This is the honesty signal that tells you which agents to trust.)
• Rank by severity; aim for a target count (e.g. 6-12) so they prioritize over dumping noise.

Scope hygiene: never delegate edits to .claude/ or .devcontainer/ (sub-agent write guards block them silently) — but read-only audit of those dirs is fine. Keep load-bearing edits in the main session later.

3. Survive the rate limit — resume, don't restart

A big fan-out often trips a transient server 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") — this reuses its accumulated context instead of paying for the reads again. Only fully restart an agent that died before doing any work (≈≤3 tool calls).

4. Confirm — independently, the high-severity items at least

The user asked to confirm findings; 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 that the agent missed, severity inflation. Drop or downgrade anything that doesn't survive your own read. Record "confirmed by independent read" per kept finding. An agent that honestly self-flagged its own non-findings (step 2) has earned lighter scrutiny than one that didn't.

For very large audits, this confirmation pass can itself be a second fan-out of code-reviewer agents, each adversarially trying to refute one finding — keep only those that survive.

5. Dedupe and cluster into parallel-safe PRs

Merge duplicates across agents (the same bug often surfaces from two lenses). Then group survivors into PRs 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. A natural grouping: one PR per subsystem (firewall, monitor, redaction, lifecycle, …), each 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 (per the project's testing doctrine — assert the invariant, not today's symptom), and a rough size.

6. Critique the plan, then deliver

Before handing over the plan, attack it: Are any "parallel" PRs actually file-conflicting? Is a "high" severity really reachable, or gated behind an opt-in 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)? Are there 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. The plan delivery is the ONE moment to batch every open question; concentrate them there.

7. Executing the plan (when asked)

When the user says to proceed from plan to fixes, 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 you have belongs in the batch delivered with the plan (step 6), before the first PR starts. 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 checklist of the PR queue and tick each off as it opens, so progress is supervisable at a glance.

Lessons baked in

• Give each agent the project's own rules to check against. A repo's CLAUDE.md usually states rules it tries to follow (e.g. "fail safe when something breaks", "this script also runs on Macs"). Hand those rules to each agent and ask "where does the code break its own rules?" — that finds far more than a generic "look for bugs" pass.
• Ask each agent to also say what it checked and found fine. An agent that only ever reports problems might be inventing them; one that says "I looked at X and it's correct" is being honest. That tells you which agents to double-check.
• If an agent runs out of quota mid-way, continue it — don't start it over. Send it a follow-up message so it picks up from where it stopped; restarting makes it re-read everything from scratch.
• Two pieces of work can run at the same time only if they touch different files. True for the agents (give each its own files so they don't overlap) and for the fix PRs (so they don't clash when merging). Grouping by area usually does this for you.
• Rank a problem by how easy it is to actually trigger, not how scary it sounds. A "critical" bug that only happens when someone turns on a dangerous off-by-default option is really a minor one. Check the problem is reachable in normal use before calling it severe.

Examples

User says: "Find dozens of security, robustness, testing, and UX issues. Use subagents and confirm their findings. Then plan parallel PRs to fix them, and critique the plan."

1. Map the repo; pull the invariants out of CLAUDE.md.
2. Launch 8 read-only general-purpose agents in one message — firewall, redaction, monitor, lifecycle, e2e-realness, UX, supply-chain, config/CI — each with a disjoint file list and the structured-finding contract.
3. Six trip a rate limit mid-read; resume each via SendMessage to its agentId.
4. As findings arrive, open the cited lines and confirm the high-severity ones by hand; drop the two that a guard upstream already handles.
5. Cluster ~70 survivors into one PR per subsystem (non-overlapping files), each with the invariant test that would catch the class.
6. Critique: two PRs both touch ip-validation.bash → merge them; one "critical" is behind --dangerously-skip-firewall → downgrade. Deliver plan + critique.