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 <project> codebase" - "find bugs / security issues / infra risks / dead code in <repo>" - "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.