---
name: deep-audit
description: "Multi-agent deep audit of any existing project or artifact. Fans out ~6 complementary specialist agents (Opus + Sonnet) across domain-appropriate dimensions, then synthesizes — surfacing convergent findings (issues 2+ agents independently flag = highest confidence), per-dimension verdicts, a severity-ranked findings table, and a prioritized fix list. Works on any domain: UI/frontend, full-stack/backend, firmware/embedded, electronics/PCB, plans/specs, or documentation. Use when anyone asks to: audit, deep-audit, review a project/codebase/design/board/firmware/plan/docs, get a second set of eyes, find what's missing, check what a single builder might have missed, or vet that nothing critical is overlooked."
user-invocable: true
argument-hint: "[path-or-project] [optional: domain or focus]"
---

# deep-audit — Multi-Agent Project Audit

Exhaustive review of an **existing** artifact (built code, hardware design, firmware, a plan, or docs) by fanning out a fleet of specialist agents — each owning a distinct audit dimension — then synthesizing their independent findings into one ranked report.

The payoff comes from two things a single reviewer can't give you:
1. **Breadth** — ~6 agents cover dimensions in parallel that one pass would skim.
2. **Convergence** — when multiple agents *independently* flag the same issue without coordinating, that's the highest-confidence signal in the whole report. Convergence detection is the crown jewel of synthesis.

**The deliverable is a written handoff document** (`audit-<date>.md`) — this skill exists to hand a project off to the engineer and the agent(s) responsible for it. The file is always written; the chat reply is just the headline.

**Total agents: typically 6** (scale 4–8 by project size/complexity).

This skill is self-contained: the **[Dimension catalog](#dimension-catalog)** and **[Agent prompt template](#agent-prompt-template)** are at the end of this file.

## How this differs from adom-plan

`adom-plan` runs **adversarial debate pairs on shared topics** to stress-test a *plan before building* (depth via conflict). `deep-audit` runs **complementary agents on distinct dimensions** to find what's wrong or missing in something *already built or in progress* (breadth via division). Reviewing a pure sketch with no code? Prefer `/adom-plan`. Reviewing a build, a board, firmware, docs, or a plan-vs-actual-build gap? Use this.

## Invocation

```
/deep-audit                          # audit the current project / working dir
/deep-audit services/api-gateway/      # audit a specific path
/deep-audit ./board firmware         # audit a path with a domain hint
"audit this project" / "find what we're missing"   # natural-language trigger
```

## Workflow

### Phase 0 — Scope & classify

Establish **what** is being audited and **what domain** it is — this drives dimension selection.

1. Resolve the target: an explicit path/arg, the current working dir, or what the user pasted/described. If ambiguous, ask one question: "What should I audit — point me at a path, repo, board file, or doc."
2. Classify the domain(s) from the artifact, not assumptions: `frontend/UI`, `backend/full-stack`, `library/SDK`, `firmware/embedded`, `electronics/PCB`, `plan/spec`, `documentation`, or **hybrid** (e.g. a plan + an in-progress codebase → plan-gap + software dimensions).
3. Note the **stage** (greenfield sketch / early build / near-production / shipped) and any **stated goal or plan doc** — the bar for "what's missing" depends on what it's trying to be.

### Phase 1 — Recon (do this yourself, before fanning out)

**Do not skip this.** Agents handed precise scope find real defects; agents told to "go audit X" waste budget rediscovering structure and overlap each other. Orient first:

- Map the artifact: file tree (excluding build/vendor dirs), size/LOC or board/BOM scale, key entry points, the plan/spec/README, and any test or verification harness.
- For code: skim the core module(s), the public surface, and how to build/run/test it.
- For hardware: locate schematic, PCB, BOM, datasheets, design rules.
- For plans/docs: read the document end to end.

Compile a **Recon Context Block** (target, domain, stage, structure summary, key file pointers, stated goals, how-to-build/test). This block is prepended to *every* agent prompt so they audit reality, not guesses — and crucially you hand each agent the **specific files** in its lane.

### Phase 2 — Select dimensions & assign models

Pick **~6 best-fit dimensions** from the [Dimension catalog](#dimension-catalog) (end of this file). For hybrid projects, mix across domains. Always include the cross-cutting lenses that apply (security/safety, verification/test coverage, plan↔reality gap, doc↔artifact drift) unless clearly irrelevant.

**Model assignment:**
- **Opus** for judgment-heavy, adversarial, or safety-critical dimensions — architecture/design integrity, correctness & safety of the core path, security, plan-gap analysis, real-time/memory safety (firmware), schematic/power/signal integrity (hardware).
- **Sonnet** for enumerable, mechanical dimensions — contract/schema/BOM diffs, test-coverage matrices, doc consistency, footprint-vs-datasheet checks, build/toolchain reproducibility.

Aim for a mix (e.g. 4 Opus + 2 Sonnet for a safety-critical build). Scale to 4 agents for a small/simple target, up to 8 for a large or high-stakes one. Tell the user the dimension/model lineup before launching.

### Phase 3 — Fan out (all agents in ONE message)

**CRITICAL: launch every audit agent in a single response message** so they run concurrently and independently. Sequential launch destroys independence and wastes time.

Each agent (use `general-purpose`, or a domain agent like `Explore` for recon-heavy lanes) gets, per the [Agent prompt template](#agent-prompt-template) (end of this file):
- The Recon Context Block (verbatim).
- Its **dimension charter** — the precise lane, the questions to answer, and the **specific files** to read.
- A mandate to be **READ-ONLY** (audit, do not modify anything).
- The **required structured output**: a one-paragraph verdict, a findings table (`title | location (file:line) | what's wrong | failure/attack scenario | severity | confidence`), and a ranked "top must-fixes" list. Severity = Critical/High/Med/Low; Confidence = High/Med/Low. Demand file:line evidence; forbid padding.

### Phase 4 — Synthesize and WRITE the handoff document (you do this — never delegate it)

Read every agent's report, then **write the full audit to a markdown file** using the structure in "Handoff document — required output" below. This file is the real deliverable: it goes to the engineer and the responsible agent(s), who will not have seen the agent reports. So it must be **self-contained** (no "see the security agent's report") and **complete** — convergent findings are highlighted, but **every** finding/risk each agent raised is carried into the doc, deduped, with its file:line, severity, and confidence. Nothing gets dropped for brevity.

**Where to write it:** `docs/audit-<YYYY-MM-DD>.md` if a `docs/` (or `doc/`) dir exists, else `<project-root>/audit-<YYYY-MM-DD>.md`. Never overwrite an existing audit file — if one exists for today, suffix `-2`, `-3`, etc. Use the real date from the environment context.

**Always drop a discoverability pointer.** After writing the audit file, add a one-line link to it from the project's primary roadmap/readme so the team finds it: `TODO.md` if present, else `README.md`, else the closest equivalent (a plan/roadmap doc). The line names the date, the headline (e.g. "N convergent findings, M critical"), and links the file. If no such file exists, don't create one — tell the user in the chat reply to link the audit from wherever they track work.

The synthesis work, in order:
1. **Overall verdict** — one honest paragraph: how mature/sound is this really vs. what it's trying to be? Production-ready? Showstoppers?
2. **Convergent findings (highest confidence)** — cross-reference all reports and surface every issue **2+ agents independently flagged**. Name which agents converged. This is the headline; these are what the team is *most* likely missing. (e.g. a config flag with no fail-closed guard, an auth check that compares a value to itself, an idempotency record written *after* the commit it is meant to dedupe — the kind of issue a lone reviewer misses.)
3. **Per-dimension verdict table** — one row per agent: dimension | verdict | standout finding.
4. **Full findings** — every finding from every agent, deduped (merge the same issue seen from two angles into one entry, noting both sources and tagging it CONVERGENT). Grouped by dimension (or by severity), each with location (file:line), severity, confidence, and the failure/attack scenario. This is the long tail the engineer works through — do not truncate it.
5. **Prioritized action TODOs** — convert the findings into an actionable, checkbox TODO list, gated into recommended build phases:
   - **NOW** — cheap fixes worth doing while the work is small, or live/critical issues to fix immediately.
   - **BEFORE NEXT GATE** — must fix before the next milestone (e.g. before a risky subsystem ships / before rollout).
   - **BEFORE PRODUCTION / FAB / RELEASE** — hard gates.

   **Label every TODO** with a stable ID so the team can refer to it in one token: `N#` for NOW, `G#` for the next-gate phase, `P#` for the production phase (e.g. `N1`, `G3`, `P2`). Number within each gate in **dependency order** — a task comes after the tasks it needs. Each TODO carries a **`deps:`** field listing the labels it depends on (`—` if none); deps may cross gates (a `G` item can depend on an `N` item). The gates are themselves the recommended phases; the `deps:` chain is the build order inside and across them. Each TODO line names *what* to do, *where* (file:line), links back to its finding ID + severity, and ends with `deps:`. Keep the highest-priority gate front and center (NOW first). Anything from a Critical finding or a failed-verdict dimension is auto-placed at its appropriate gate.

## Handoff document — required output

Write the file in this shape. It is read by an engineer and the agent(s) who own the project, who did NOT see the agent reports — so spell everything out. Convergent items are highlighted but **all** findings appear. No emojis anywhere in the file.

```markdown
# Deep-Audit — <project> — <YYYY-MM-DD>

**Scope:** <what was audited> · **Domain:** <…> · **Stage:** <…>
**Method:** <N>-agent deep-audit (<list dimensions + models>)
**For:** handoff to <engineer / owning agent>

## Overall verdict
<one honest paragraph: maturity vs intent, production-readiness, showstoppers>

## Convergent findings (highest confidence)
> Issues 2+ agents flagged independently — start here.
| ID | Finding | Converging dimensions | Severity | Why it matters |
|----|---------|----------------------|----------|----------------|
| C1 | … | Security + API | Critical | … |

## Action TODOs
> Checkbox list for the receiving engineer/agent. Labels (N#/G#/P#) are stable handles; `deps:` defines build order. Highest gate first.

### NOW (live / critical / cheap-now)
- [ ] **N1** — <action> — `<file:line>` — <one line why> _(F<id>, Critical)_ · deps: —

### BEFORE NEXT GATE (<the gate, e.g. company rollout>)
- [ ] **G1** — <action> — `<file:line>` — … _(F<id>, High)_ · deps: N1

### BEFORE PRODUCTION / FAB / RELEASE
- [ ] **P1** — <action> — `<file:line>` — … _(F<id>, Med)_ · deps: G1

## Per-dimension verdicts
| Dimension | Model | Verdict | Standout finding |
|-----------|-------|---------|------------------|

## Full findings
> Every finding from every dimension, deduped. CONVERGENT items cross-referenced to their C-id.
### <Dimension 1>
| ID | Title | Location | Severity | Confidence | Issue & failure scenario |
|----|-------|----------|----------|------------|--------------------------|
### <Dimension 2>
…

## Notes for the next agent
<resident agent IDs to continue via SendMessage; anything the auditors flagged low-confidence that needs a human/owner call; what was NOT covered.>
```

Tally a **finding count** (total, and by severity) and an **action count by gate** at the top or bottom so the reader sees the shape at a glance.

### Phase 5 — Present to user

1. Tell the user **the file path** you wrote, first.
2. Lead with the **overall verdict** (1–2 sentences) and the **convergent critical findings** — the headline.
3. Print the **per-dimension verdict table** and **action-item counts** by gate (NOW / NEXT GATE / PRODUCTION).
4. Note that **the agents are still resident** — offer to send follow-ups (e.g. "have the safety agent draft fixes for the convergent items") via SendMessage.
5. Offer next steps: spawn a fix-it agent for the NOW items, or drill into one dimension.

## Guidelines

- **Recon before fan-out, always.** Precise per-agent file pointers are the difference between real defects and generic hand-waving.
- **All audit agents in ONE message.** Independence is the whole point; concurrent launch preserves it and is faster.
- **Convergence is the signal.** Two agents independently hitting the same issue outranks one agent's confident lone finding. Lead with it.
- **Complementary, not overlapping.** Give each agent a distinct lane so coverage is broad. Some natural overlap (security ↔ safety) is fine and *feeds* convergence — but the charters should differ.
- **Match dimensions to domain.** A PCB audit and a React-app audit share almost no lenses. Use the catalog; don't run software dimensions on a board.
- **Read-only.** Auditors observe and report. Fixing is a separate, explicit follow-up the user opts into.
- **Evidence or it didn't happen.** Demand file:line (or schematic ref / datasheet page / doc line) for every finding; flag unverified claims with low confidence rather than asserting them.
- **Synthesize honestly.** Report failed verdicts and showstoppers plainly. If "55 tests green" doesn't mean what a reader assumes, say so.
- **No emojis in the handoff `.md`.** Use plain text labels (severity words, `N#`/`G#`/`P#`, `CONVERGENT`) — never emoji for headings, severity, or gates. It's an engineering handoff doc.
- **Scale to stakes.** Safety-critical or production-bound → more agents, more Opus, adversarial framing. Quick sanity check → 4 agents, lean.
- **Leverage platform tools for hardware.** Electronics audits can pull `adom-inventory` / `adom-parts-search` for BOM availability and the wiki for datasheets — wire those into the relevant agent's charter.

---

## Dimension catalog

Pick ~6 dimensions from the domain that fits the target. For **hybrid** targets (e.g. a plan + an in-progress build, or a board + its firmware), mix across sections. The **cross-cutting** lenses at the bottom apply to almost anything — fold them in unless clearly irrelevant.

`[O]` = assign **Opus** (judgment/adversarial/safety). `[S]` = assign **Sonnet** (enumerable/mechanical). These are defaults; override by stakes.

### Software — backend / full-stack / library

1. **Plan ↔ build gap & completeness** `[O]` — what the plan/README/spec commits to vs. what code actually exists. Classify each capability DONE / PARTIAL / MISSING / STUBBED. Find missing whole subsystems, speculative builds atop unanswered questions, and doc↔code drift.
2. **Architecture & abstraction integrity** `[O]` — module boundaries, layering, coupling, leaky abstractions, dependency direction. Will the seams carry what's coming (real adapters, new callers)? Refactors that are cheap now and expensive later.
3. **Correctness & safety of the core path** `[O]` — the data/write/decision path. Concurrency & locking, atomicity, fail-open vs fail-closed, error handling, edge cases, idempotency, state-machine soundness. Hunt real defects with concrete failure scenarios.
4. **Security** `[O]` — authn/authz, input validation at trust boundaries, injection (SQL/path/command/XML), secrets & PII handling/logging, DoS/rate-limiting, dependency CVEs. Map the attack surface; worst-case blast radius of one bad request.
5. **Contracts / API / schema fidelity** `[S]` — wire/API/DB-schema definitions vs. what code emits and consumes; cross-service or cross-repo lockstep; single-source-of-truth vs. hand-maintained copies (drift risk); versioning.
6. **Test coverage & verification rigor** `[S]` — run the suite; report real pass/fail vs. claimed. Map coverage to a risk matrix; flag tautological/weak tests, fake-only blind spots, and the highest-value missing tests ranked by risk×effort.
7. *(optional)* **Observability & ops-readiness** `[S]` — metrics/logs/traces/health, runbook, deploy/rollback, config & startup recovery.
8. *(optional)* **Performance & scalability** `[O/S]` — hot paths, allocations, N+1s, unbounded growth, load behavior.

### Software — frontend / UI

1. **UX & interaction correctness + accessibility** `[O]` — flows, edge/empty/error/loading states, keyboard nav, focus, ARIA, contrast, screen-reader semantics.
2. **State management & data-flow correctness** `[O]` — source-of-truth, stale/race conditions, cache invalidation, optimistic-update correctness, effect dependencies.
3. **Visual / design-system fidelity & responsive behavior** `[S]` — adherence to the design system/brand, breakpoints, overflow, theming, layout robustness. (For Adom UIs, check brand/design-system via the `adom` skill.)
4. **Performance** `[S]` — render thrash, bundle size, network waterfalls, image/asset weight, memo/virtualization gaps.
5. **Client security** `[O]` — XSS/`dangerouslySetInnerHTML`, auth-token handling, secrets shipped to client, CSP, unsafe deps.
6. **Component architecture & reuse / tech-debt** `[O]` — composition, prop drilling, duplication, dead code.
7. *(optional)* **Test coverage** `[S]` — unit/integration/e2e/visual-regression.

### Firmware / embedded

1. **Real-time & concurrency correctness** `[O]` — ISR safety, shared-state races, priority inversion, deadlocks, blocking in critical sections, timing assumptions, `volatile`/atomics, reentrancy.
2. **Memory & resource safety** `[O]` — buffer overflows, stack depth/overflow, heap fragmentation/leaks, static allocation budgets, pointer/lifetime bugs, DMA buffer ownership.
3. **Hardware-interface correctness** `[O]` — register init order, peripheral config vs. datasheet, clock/timing, pin mux, errata. (Pull datasheets via `adom-wiki`; cross-check pin maps with `adom-pin-mapping`.)
4. **Power / reset / fault handling** `[O]` — brown-out, watchdog, recovery paths, safe-state on fault, sleep/wake, GPIO state through reset.
5. **Comms/protocol correctness** `[S]` — I²C/SPI/UART/CAN/USB framing, CRC/checksums, retry/timeout, endianness, buffer over/underrun.
6. **Build / toolchain / flashing reproducibility** `[S]` — pinned toolchain, linker map & section placement, optimization-level hazards, bootloader/OTA integrity, reproducible builds.
7. *(optional)* **Test / HIL coverage** `[S]` — unit, on-target, hardware-in-loop, fault injection.

### Electronics / PCB / hardware design

1. **Schematic correctness** `[O]` — net connectivity, pin assignments, no-connects, power/ground nets, bypass topology, reference designators, ERC.
2. **Power integrity & thermal** `[O]` — rail budget & sequencing, regulator headroom, decoupling adequacy, current-carrying capacity, thermal dissipation, inrush.
3. **Signal integrity & layout/EMC** `[O]` — controlled-impedance traces, length matching, return paths, grounding/stitching, crosstalk, connector/antenna placement, EMC risk.
4. **Component selection & BOM** `[S]` — voltage/current/temp/power ratings vs. use, tolerances, lifecycle/availability, second sources. (Use `adom-inventory` for on-hand stock and `adom-parts-search`/distributor skills for availability & pricing.)
5. **Footprint / symbol / library fidelity** `[S]` — land patterns vs. datasheet, pin-1 orientation, courtyard, paste/mask, 3D model sanity. (Cross-check via `adom` KiCad tooling.)
6. **DFM / DFA / manufacturability** `[S]` — fab clearances & rules, assembly access, panelization, test points, silkscreen legibility.
7. **Protection & design-for-test** `[O]` — ESD, reverse-polarity, over-current/fusing, transient suppression, test/debug access, programming headers.

### Plan / spec document

> For a *pure* sketch with no build yet, prefer `/adom-plan` (adversarial debate). Use deep-audit when comparing a plan against an in-progress build, or for a completeness/feasibility sweep.

1. **Completeness & gap analysis** `[O]` — unspecified behaviors, missing subsystems, hand-waved hard parts.
2. **Feasibility & technical soundness** `[O]` — does the approach actually work given platform/physics/constraints? Hidden assumptions.
3. **Risk & failure-mode coverage** `[O]` — what breaks, what's unmitigated, the realistic failure scenario nobody planned for.
4. **Dependency, sequencing & critical-path realism** `[S]` — ordering, blocked-on items, schedule honesty, gating questions.
5. **Security / safety considerations** `[O]` — threat model, safety gates, blast radius.
6. **Clarity & ambiguity** `[S]` — terms/requirements an implementer will misread; under-specified contracts.

### Documentation

1. **Accuracy vs. reality (drift)** `[O]` — claims that the code/hardware contradicts; stale instructions; outdated file/flag references.
2. **Completeness & coverage gaps** `[S]` — undocumented features, missing setup/ops/troubleshooting sections.
3. **Runnable examples & commands** `[S]` — do the documented commands/snippets actually work? Try them.
4. **Clarity, structure & audience fit** `[S]` — organization, onboarding path, assumed knowledge.
5. **Security hygiene** `[S]` — leaked secrets/tokens, unsafe or destructive instructions presented without warning.
6. **Consistency** `[S]` — terminology, cross-references, broken links, version skew.

### Cross-cutting (fold into any domain)

- **Plan ↔ reality gap** `[O]` — promised vs. delivered, for whatever the "promise" artifact is.
- **Security / safety** `[O]` — the trust/safety boundary appropriate to the domain.
- **Verification & test coverage** `[S]` — does the testing prove what a reader assumes it proves?
- **Doc ↔ artifact drift** `[S]` — do the docs match the thing?
- **Dependency / supply-chain** `[S]` — pinned versions, known-vuln deps, build provenance.

## Agent prompt template

Fill the `{{...}}` slots. Give each agent a *distinct* dimension and the *specific files* in its lane. Launch all in one message.

```
You are one specialist in a multi-agent deep audit of {{TARGET}} ({{DOMAIN}}, stage: {{STAGE}}).
Your dimension: **{{DIMENSION NAME}}**. Stay in this lane — other agents cover the rest.
This is a STRICTLY READ-ONLY audit. Do not modify, create, or delete any file.

## Context (shared recon — treat as ground truth, verify against current files)
{{RECON CONTEXT BLOCK: target, domain, stage, structure summary, stated goal/plan,
how to build/run/test}}

## Read these first
{{PRECISE FILE POINTERS for this dimension — the plan/spec section, the source files,
the schematic/BOM, the test dir, etc.}}

## Your charter
{{3–7 concrete questions this dimension must answer — the lane-specific probes from the
catalog entry above, tailored to this target. Be adversarial and concrete: hunt real
defects, name failure/attack scenarios, don't just describe the code.}}

If your dimension involves a runnable check (tests, a build, a command, a validator),
RUN it and report actual results vs. any claimed results. {{Include exact run commands
if known, e.g. the dotnet/PATH prefix.}}

## Required output (your final message IS the report — no preamble)
1. **{{Dimension}} verdict** — one honest paragraph. Is this sound / production-ready?
   Top showstoppers?
2. **Findings table**: title | location (file:line / ref) | what's wrong | failure-or-attack
   scenario | severity (Critical/High/Med/Low) | confidence (High/Med/Low)
3. {{Optional dimension-specific section: e.g. risk-register reality-check, coverage
   matrix, BOM ratings table, 3-/4-way contract comparison}}
4. **Top must-fixes** for this dimension, ranked.

Cite file:line (or schematic ref / datasheet page / doc line) for every finding. Mark
uncertain findings low-confidence rather than asserting them. No padding.
```