deep-audit

Deep Audit: Wave-Based Repo Orchestrator

Run up to 29 audit agents against a repo in 5 sequential waves. This is the broadest application-repo dispatch plan (4 Wave 2 + up to 20 conditional Wave 3 lenses + 2 Wave 4 + 3 Wave 5), not the total skill count. Wave 1 detects the tech stack, Waves 2-5 dispatch only matching audit skills, and each wave reports before the next begins.

The five waves are: Reconnaissance; Code Quality (code-review, anti-slop, anti-ai-prose, code-slimming); Domain-Specific (detected skills only); Security (security-audit then zero-day); and Docs & Hygiene (update-docs, roadmap, git).

After the waves, Steps 7-9 persist findings to docs/local/audits/DEEP-AUDIT.md, write DEEP-AUDIT-TASKS.md, and route SMALL audits to the task list or LARGE audits to a brainstorming skill or generated plans under docs/local/specs/ and docs/local/plans/.

For a quick 4-skill sweep, use full-review instead.

When to use

• Major pre-release quality gate where you want every applicable audit lens
• First audit of an unfamiliar codebase - understand what's there and what needs fixing
• Periodic deep health check on a repo you maintain
• Onboarding to a new project - the wave reports build a mental model fast

When NOT to use

• Quick quality check on a PR or recent changes - use full-review (4 skills, parallel)
• Single-dimension audit (e.g., only security or only code quality) - use the individual skill directly (security-audit, code-review, etc.)
• Auditing the skill collection itself - use skill-creator (Mode 3)
• Offensive security engagement or CTF - use lockpick directly
• Live-system OS administration (running pacman/apt/dnf, fixing a NixOS rebuild, configuring SELinux on a host, debugging an OPNsense appliance) - use the matching distro/appliance skill directly (arch-btw, debian-ubuntu, rhel-fedora, nixos-btw, firewall-appliance). Repo-level audit of OS-related files (PKGBUILDs, debian/, *.spec, flake.nix, pf.conf, etc.) belongs in Wave 3 of this skill

AI Self-Check

Run after Step 9 completes, before concluding the session. Checks cover the full workflow (waves + persistence + routing), not just the wave dispatch phase.

• [ ] All agents dispatched as general-purpose type (not feature-dev:, code-simplifier:, or other restricted types - these lack Skill tool access)
• [ ] Each agent invoked its assigned custom skill via the Skill tool as its first action
• [ ] Recon summary (Wave 1) was presented to the user before Wave 2 agents were dispatched
• [ ] Wave 2 (code quality) ran all 4 skills regardless of repo type
• [ ] Wave 3 (domain) ran only skills whose detection patterns matched - no false activations
• [ ] Wave 3 skills that were skipped are listed by name in the recon summary
• [ ] Wave 4 ran sequentially: security-audit completed before zero-day started
• [ ] Zero-day agent received a summary of security-audit findings as input context
• [ ] Each wave's results were presented before the next wave started
• [ ] Each skill's native report format was preserved - no normalization across reports
• [ ] Failed or timed-out agents noted with reason, not silently dropped
• [ ] docs/local/ added to .gitignore before writing any audit artifacts (verified with git check-ignore)
• [ ] docs/local/audits/DEEP-AUDIT.md written consolidating all wave findings in their native format
• [ ] Root-level SECURITY-AUDIT.md (if written by security-audit) relocated into docs/local/audits/
• [ ] docs/local/audits/DEEP-AUDIT-TASKS.md written with phased checklist (priority, effort, files, rationale per task)
• [ ] Task-list size assessed; routing decision announced (SMALL: direct action list, LARGE: brainstorming handoff or vanilla-harness plan generation)
• [ ] If LARGE and a brainstorming skill is available, user was told to invoke it manually (no silent auto-invocation)
• [ ] If LARGE and no brainstorming skill is available, execution-plan files written to docs/local/specs/ and docs/local/plans/ using the standard naming convention
• [ ] When user specified a scope, all agents received that scope constraint and detection was filtered to the scoped file tree
• [ ] Only skills from the iuliandita/skills collection were used - no built-in reviewers or platform audit modes
• [ ] Current source checked: dated versions, CLI flags, API names, and support windows are verified against primary docs before repeating them
• [ ] Hidden state identified: local config, credentials, caches, contexts, branches, cluster targets, or previous runs are made explicit before acting
• [ ] Verification is real: final checks exercise the actual runtime, parser, service, or integration point instead of only linting prose or happy paths
• [ ] Routing overlap checked: overlapping skills, trigger terms, and "When NOT to use" boundaries are checked before returning guidance
• [ ] Spec claims verified: claims about tool behavior, output contracts, or repo conventions are checked against current docs, scripts, or skill files
• [ ] Scope bounded: audit waves match the repo type and user request, not every possible skill
• [ ] Evidence retained: findings cite files, commands, outputs, or source docs instead of impressions

Performance

• Inventory first, then choose high-risk slices; avoid full exhaustive scans when focused evidence answers the question.
• Run cheap global searches before expensive test suites or dynamic analysis.
• Batch findings by subsystem and severity so review effort scales with risk.

Best Practices

• State residual risk and skipped areas explicitly.
• Separate confirmed findings from hypotheses and follow-up tasks.
• Do not mutate the repo during an audit unless the user requested fixes.

Workflow

Step 0: Preflight

Gather context. Run in parallel (guard each with ; true):

1. Repo state: git rev-parse --show-toplevel and git rev-parse --short HEAD
2. Branch: git branch --show-current
3. File count: git ls-files | wc -l

If not a git repo: stop. Tell the user: "deep-audit requires a git repository - the wave agents use git context for file discovery, diff scope, and commit anchoring. Initialize a repo with git init and commit the files, then re-run."

Record preflight values. Default {scope} to "full codebase" unless the user specifies a narrower target.

Step 1: Reconnaissance (Wave 1)

Detect which Wave 3 skills apply by scanning for file patterns. Use the detection table and script in references/detection-patterns.md.

Run the detection script from the repo root. It outputs matched skill names, one per line. If the user specified a scope, pass it as the script's first argument to filter detection to that subtree (git ls-files -- path/to/scope instead of the full repo).

After detection, present the recon summary before proceeding. Compute {unmatched_skills} as the 20 Wave 3 candidates minus the matched set. Compute {count} by summing: 4 (Wave 2) + matched Wave 3 skills + 2 (Wave 4) + 3 (Wave 5). Example: if 6 Wave 3 skills match, count = 4 + 6 + 2 + 3 = 15. If the matched Wave 3 set is too broad for the user's goal, recommend a scoped deep-audit or full-review instead of pretending every lens is equally valuable.

In scoped mode, separate Wave 3 matches into two lines: skills matched by files within the scoped subtree, and skills matched only by repo-root manifests (potential false activations from workspace-root deps). Dispatch both sets - the invoked skill will report zero findings if its domain isn't actually in scope. The [root-manifest] separation is for user transparency, not gating.

If the user stated a priority (e.g., "security is top priority"), acknowledge it in the recon summary: "Security is prioritized - it runs in Wave 4 as designed; wave order is fixed because earlier waves feed context into security analysis." Do not reorder waves.

## Wave 1: Re