codebase-audit

Codebase audit

Whole-repo counterpart to change-review. Where change-review reviews a changeset, this audits the entire tree across three lenses in one pass. Report-only — it never edits, fixes, or commits. Every finding carries file:line so a later /code-review --fix, change-review --fix, or manual pass can act on it.

Built-in /code-review and /security-review are change-scoped (they operate on the branch diff), so this skill does NOT call them — it reuses their lenses and finding format, applied by fan-out agents over slices of the repo. /ponytail-audit is the exception: it is already whole-repo scoped, so the over-engineering lens is delegated to it rather than reimplemented inline, and its findings are folded into the Over-engineering section.

0. Parse arguments

• Optional path — audit only that subtree (default: repo root).
• --effort low|medium|high|max — depth of each slice agent's review. Defaults to the reviewer's own default tier.

1. Scope the tree and estimate cost

List in-scope files with git ls-files (respects .gitignore); if a path is given, scope to it. Exclude mechanical/generated content: lockfiles (package-lock.json, yarn.lock, poetry.lock, Cargo.lock), build output (dist/, build/, *.min.*), vendored dirs (node_modules/, vendor/), and generated files (snapshots, codegen, *.generated.*).

Count files and total lines in scope, then print an approximate cost estimate before the fan-out, e.g.:

Auditing 214 files (~38k lines) across ~12 slices → ~12 agents. Full-repo pass, may be token-intensive. Proceeding.

There is no size cap — full coverage — so the estimate is the guardrail. For a very large tree, say so plainly so the user can interrupt.

2. Slice the tree

Group in-scope files into size-bounded slices, one per coherent module/directory:

• Keep a slice within ~15 files or ~2000 lines, whichever comes first.
• Don't split a small directory; split an oversized one by subdirectory or file.
• Keep files read together (a module and its tests) in the same slice.

3. Over-engineering lens — delegate to /ponytail-audit

Run /ponytail-audit once over the in-scope tree (forward the path argument when given; it is report-only and takes no effort flag). It self-slices the whole repo, so do not also fan out over-engineering per slice. Map each of its ranked findings (<tag> <what to cut>. <replacement>. [path]) into the common finding shape below with category: over-engineering, and keep its net: -<N> lines, -<M> deps line for the section footer.

4. Fan out — one agent per slice (correctness + security)

Dispatch one Agent per slice (batch to a sane concurrency — don't launch hundreds at once). Give each agent the slice's file list and instruct it to apply both lenses below in a single read and return findings as JSON.

Correctness (/code-review lens): real defects with a concrete failure scenario (null/undefined, off-by-one, wrong error handling, race, resource leak), plus reuse/efficiency issues.

Security (vuln taxonomy): injection (SQL/command/template), SSRF, path traversal, insecure deserialization, missing authn/authz, secrets in code, unsafe crypto. /security-review is change-scoped, so this taxonomy is the lens.

Each finding: { file, line, category (over-engineering|correctness|security), severity (high|med|low), confidence (0-100), summary, detail, suggestion }.

5. Confidence scoring

Same scale as change-review:

• 0–49: uncertain / possible false positive — surface as a suggestion.
• 50–79: likely real but low-impact — suggestion.
• 80–100: verified, high-impact, or a clear vuln — a blocker.

Report all findings; do not drop by score.

6. Synthesize

Collect the correctness/security findings from the slice agents plus the over-engineering findings from /ponytail-audit. Dedup issues that span slice boundaries (same root cause reported twice). Rank: security and correctness by severity × confidence; over-engineering biggest-cut first.

Assign every finding a unique, stable ID by lens, numbered in report order: OE-1, OE-2, … (over-engineering), CO-1, … (correctness), SE-1, … (security). The ID is how a finding is referenced in the Verdict and by any later fix pass (change-review --fix, /code-review --fix), so keep it stable and never reuse a number within one report. Produce the report below.

7. Output format

## Codebase audit — <path or repo>, <N> files / ~<L> lines, <S> slices

### Over-engineering
- **OE-1** <file:line> — <tag> <what to cut> → <replacement> (confidence N)   (or: Lean already)
_net: -<N> lines / -<M> deps possible_

### Correctness
- **CO-1** [HIGH/MED/LOW] <file:line> — <bug + failure scenario> → <fix> (confidence N)   (or: No obvious defects)

### Security
- **SE-1** [HIGH/MED/LOW] <file:line> — <vuln> → <remediation> (confidence N)   (or: No issues found)

### Verdict
**Must fix:**
- <finding ID + one-line, high-severity/high-confidence, ordered>   (or: None)

**Worth doing:**
- <finding ID + one-line, med/low items>   (or: None)

<one line: overall health + the single highest-value action (by ID)>

Every finding leads with its ID (§6) so the Verdict and any later fix pass can reference it.

Report-only. Do not edit, fix, or commit — the file:line anchors are the seam for a separate fix pass.

Notes

• Relationship to change-review and the deep passes: see ../change-review/review-skills-map.md (§ "Whole-repo vs diff").
• Respect the repo's own stated rules (CLAUDE.md / AGENTS.md / CONTRIBUTING) over generic priors.
• For large trees, fan out with the Agent tool; the final report must still follow the structure above.