codebase-audit

Codebase Audit

A read-only harness that turns "audit this project" into a consistent, scannable *_AUDIT.md report: findings with file:line evidence, a rating, a one-line fix, a prioritized execution order, and a verification plan. Every run starts fresh and rewrites the report from scratch — it does not read, reuse, or carry over a previous audit.

When to use / not use

• Use for whole-project assessment that produces a document: "audit the codebase", "find complexity / smells", "quality audit", "where are the security gaps".
• Don't use for a single diff/PR (use a diff-level review skill/command if your setup has one) or to apply fixes. This skill writes a report and stops — it ends by offering to fix, never by fixing.

Step 0 — Pick the lens

If the user didn't say, ask which lens (see Lens Packs below). One report = one lens. Name the output docs/COMPLEXITY_AUDIT.md, docs/QUALITY_AUDIT.md, docs/SECURITY_AUDIT.md, etc. Create the docs/ directory if it does not exist.

The method

1. Survey. Get the shape before diving in — adapt commands to the project's language(s):
   • git ls-files | grep -vE 'node_modules|vendor|dist|build|\.venv' for the tree.
   • Line counts of source, sorted desc. Match the project's source extensions (ts|tsx|js|py|go|rb|java|kt|cs|rs|php|...): git ls-files | grep -E '\.(ts|tsx|js|py|go|...)$' | grep -vE 'node_modules|vendor|test|spec|stories' | xargs wc -l | sort -rn | head -40
   • Rank hotspots by churn × size, not size alone — the riskiest files are the big ones that also change the most. Get churn from history and prefer files high on both lists: git log --format= --name-only --since='12 months ago' | grep -E '\.(ts|tsx|js|py|go|...)$' | sort | uniq -c | sort -rn | head -40. Point the fan-out (step 4) at that intersection first.
   • Read the project's manifest / build config (package.json, pyproject.toml/requirements.txt, go.mod, pom.xml/build.gradle, Cargo.toml, *.csproj, …), type/lint/format config, and CI workflows. Identify the stack first; everything below adapts to it.
   • Capture a metrics baseline (see report skeleton): test-coverage % if the tool reports it, total source LOC, dependency count, and the lens's key signal count (e.g. type suppressions). Captured consistently each run, these numbers let a reader compare report versions in git for a measurable delta, not just prose — without this run needing to read the prior audit.
2. Check for context docs FIRST. Glob *.md for AGENTS.md, CLAUDE.md, DESIGN.md, ARCHITECTURE.md. Read them. Cross-reference, never duplicate — if an item is already tracked there, point at it instead of re-listing it. State this in the report's intro. Ignore any prior docs/*_AUDIT.md — do not read it or treat it as a baseline. This run produces a brand-new audit; if a docs/<LENS>_AUDIT.md already exists it is overwritten wholesale.
3. Run the project's own analyzers first. Before (or alongside) reading code, run whatever static analysis the stack already has and fold the real output into findings — a tool hit is reproducible signal, stronger than model judgment. Use what's installed: eslint, tsc --noEmit, ruff/mypy, gosec/govulncheck, semgrep, bandit, cargo clippy, npm audit/pip-audit, the project's coverage runner, etc. Don't install heavyweight tools or fail the audit if none exist — note their absence as a finding (missing CI gate). Cite analyzer output as evidence like any other finding, and de-dupe it against what the agents find.
4. Fan out. Launch ≤3 Explore agents IN PARALLEL (one message), each scoped to a slice of the lens's dimensions (see packs). Tell each: read files in full, quote code, give file:line references, do NOT propose fixes — just catalog. For signal-counting (type suppressions, casts, debug prints, TODO/FIXME, swallowed errors — pick patterns that fit the project's language) run targeted grep yourself in parallel — and sanity-check counts (a greedy regex inflates them; verify suspicious numbers with a tighter pattern).
5. Catalog. Every finding needs: a file:line, a quoted snippet or precise description, and why it matters (the failure it invites), not just what it is.
6. Rate. Use the lens's rating vocabulary (below), consistently. Higher = worse.
7. Prioritize. Sort into a summary table by impact × recurrence. Recurrence matters: a small smell repeated ×5 outranks a medium one-off.
8. Propose. One refined proposal per finding (or per cluster of identical findings), with concrete step-by-step fix instructions that reuse existing utilities where they exist.
9. Plan the order. Sequence the proposals as independently shippable, behavior-preserving steps — easiest/highest-leverage first; note dependencies between them.
10. Verify. A section describing how to prove no regression: the project's test/lint/build commands, any visual/manual checks the stack supports (e.g. Storybook or visual diffs for UI), and any lens-specific reproduction (e.g. for a prod-only bug, how to reproduce it locally).