Codebase Audit

Codebase Audit Skill

Run a read-only, token-disciplined deep-dive of a codebase and produce ONE structured report — bugs, security gaps, infrastructure risks, unwired/dead/partial code, and optimizations — each finding ranked by severity and cited to file:line or the grep pattern that surfaced it. Security and infrastructure are the highest-priority areas unless the caller says otherwise.

The goal is maximum insight per token, not a file-by-file recital. The efficiency rules below are load-bearing — applied ruthlessly, they let one pass cover a large repo without blowing the budget. (Phase-2 claude-code hooks enforce rules 1 & 3 mechanically; until then they are a hard discipline you self-enforce.)

When to use

• "investigate / deep-dive / audit / review the codebase"
• "find bugs / security issues / infra risks / dead code in "
• "what's broken, risky, or half-finished here?"
• Pre-merge or pre-handoff assessment of an unfamiliar repo.

When NOT to use

• Making the fixes — this skill only REPORTS. Hand findings to an implement loop after.
• Visual/UX/CRO review — use frontend-audit.
• A single known bug — just debug it; don't audit the whole repo.

Inputs / parameters

• repo (required): the working directory to audit (the agent runs IN this cwd).
• focus (optional): risk areas to emphasize (default: all five categories).
• priority (optional): which categories rank highest (default: Security, Infrastructure).
• Always read-only. Never edit, never run mutating commands.

RULE 1 — Token discipline (HIGHEST priority)

• Never read the same file twice. Track what you've read; if you feel the urge to re-open a file, STOP and synthesize from what you already have.
• Never read build/generated dirs: node_modules, .next, dist, build, pycache, .pytest_cache, .venv, vendor, target, coverage, lockfile internals.
• Prefer Grep (with head_limit) and Glob over listing a directory + reading files.
• When you do read a file, use offset + limit — read the relevant span, not the whole file, unless it is genuinely small or you genuinely need all of it.
• Read CLAUDE.md / SKILLS-INDEX.md / README.md for a directory FIRST — they often replace opening a dozen source files.

RULE 2 — Strategy (follow this order)

1. Root config + governance only, first: the deploy/runtime/dependency manifests for the stack (Dockerfile, docker-compose.yml, fly.toml, vercel.json, requirements.txt / pyproject.toml, package.json, CI workflows) + every CLAUDE.md. These define the attack surface, the infra, and the conventions in a handful of reads.
2. Broad Grep sweeps for the risk areas (see RULE 4's pattern bank) — security, infra, TODO/FIXME/HACK, unwired features, silent-failure patterns, auth/rate-limit/webhook gaps. Let the grep hits point you to high-signal files.
3. Drill into a specific file ONLY when grep or a CLAUDE.md flags it as high-signal.
4. Any directory with >20 files -> Grep/Glob first. Never list-and-read-everything.

RULE 3 — Anti-waste hard constraints

• Do not list or walk generated/build dirs (RULE 1's list).
• Do not re-read a file you have already read, even when a "different" angle tempts you.
• Do not run the full test suite, builds, installs, or anything mutating — read-only.
• If grep already answered the question, do not open the file to "confirm."

RULE 4 — Risk pattern bank (grep starting points; adapt to the stack)

• Security: code-eval / dynamic-exec calls, pickle/deserialization, subprocess or child_process with shell enabled, dangerouslySetInnerHTML, raw SQL string concatenation, TLS verification disabled, hardcoded secret|token|api[_-]?key|password, non-constant-time token compares, permissive CORS *, routes missing auth/middleware, JWT alg:none.
• Infrastructure: unpinned deps / latest tags, 0.0.0.0 binds, missing healthchecks, no resource limits, secrets committed in env files, single-replica stateful services, missing retries/timeouts on outbound calls, unbounded queues/caches (OOM), missing rate limits.
• Unwired / dead / partial: TODO|FIXME|HACK|XXX|WIP|"not implemented"|stub|placeholder, exported symbols with zero importers, routes defined but never registered, feature flags that gate nothing, env vars read-but-never-set (or set-but-never-read).
• Silent failures: bare except / except Exception: pass, empty catch blocks, swallowed promise rejections, ignored return codes, blanket lint-disable, error logged-not-raised.
• Bugs: off-by-one, missing await, mutable default args, races on shared state, unhandled None/undefined, resource leaks (unclosed files/connections).

RULE 5 — Output contract

Produce ONE final structured report at the end. No running commentary, no file-by-file narration, no "reading X..." play-by-play. Organize by category, severity-ranked within:

# Codebase Audit — <repo>   (read-only; no edits made)

## Security            [highest priority]
- [CRITICAL] <finding> — path/file.py:120-134   (or: surfaced by grep <pattern>)
- [HIGH] ...
## Infrastructure      [highest priority]
## Bugs & Issues
## Unwired / Dead / Partial Code
## Optimizations

## Summary
- N findings: X critical, Y high, Z medium. Top 3 to fix first: ...
- Coverage note: what was sampled vs exhaustively read (be honest about gaps).

Severities: CRITICAL (exploitable / data-loss / outage), HIGH, MEDIUM, LOW. Every finding MUST cite file:line-range OR the grep pattern that surfaced it. No finding without evidence — if you cannot cite it, you did not verify it; drop it or mark it UNVERIFIED and say which read would confirm it.

Ultrathink, but ruthlessly efficient

Think hard about systemic risk and what the code is not doing — but obey RULES 1 & 3 without exception. A re-read or a node_modules walk is a budget leak; the discipline IS the skill. Maximum insight per token.