Codebase Deep Audit

A deterministic, no-nitpick audit that grounds every finding in real evidence from the codebase. Produces a 0-100 score and a prioritized fix list — nothing else, no fluff.

Core principles (non-negotiable)

1. No nitpicks. Style preferences, naming opinions, "I would have written it this way" — all banned. Only findings that map to a measurable risk (security, reliability, maintainability cost, performance, correctness) are recorded.
2. Grounded in evidence. Every finding MUST include path/to/file.ext:line_number and a one-line excerpt of the actual code. No file:line, no finding. If the issue spans multiple files, list all of them.
3. Think before speaking. Reconnaissance phase is mandatory and happens before ANY finding is written. Findings written during recon are discarded.
4. Deterministic scoring. Use the rubric in references/scoring-rubric.md. Two runs on the same codebase at the same commit must produce the same score (±2 points for non-deterministic tool output).
5. Project-type aware. Detect the project type first; apply the matching category set. Don't audit a CLI tool for accessibility.
6. Actionable only. Every finding must answer: what to do, where, and why it matters. If you can't write the fix in one sentence, the finding is too vague — drop it.

Phase 0: Reconnaissance (think before speaking)

Do ALL of this before recording any findings. Output nothing to the user during this phase except a brief "Starting audit..." acknowledgment.

0.1 Detect project type

Run these checks in order. A project can have multiple types (e.g., fullstack = frontend + backend).

Record detected types. The category set for scoring depends on this.

0.2 Detect primary languages

Use file extension counts. Record top 3 languages by LOC. This determines which language-specific rules apply (e.g., Python → check for mutable default args; JS/TS → check for == vs === in security-sensitive code; Go → check for unhandled err).

0.3 Map the codebase shape

Record:

• Total LOC (excluding node_modules, .venv, dist, build, vendored deps)
• Number of source files
• Top-level directory structure (depth 2 max)
• Entry points (main files, bin/, route files)
• Test directory presence and rough test count
• Lockfile presence (package-lock.json, poetry.lock, go.sum, etc.)
• CI config presence (.github/workflows/, .gitlab-ci.yml, etc.)

0.4 Identify the threat surface

Before security review, identify what this codebase actually exposes:

• HTTP endpoints (search for route definitions)
• Database connections (search for connection strings, ORM init)
• File I/O paths (especially user-controlled paths)
• Subprocess/shell execution (exec, spawn, os.system, subprocess)
• Deserialization (pickle, eval, JSON.parse on untrusted input)
• External API calls (auth handling, secret usage)

If the codebase has zero attack surface (e.g., a pure data analysis script), security category weight gets redistributed. See scoring rubric.

0.5 Decide the category set

Based on detected project types, select categories from references/category-matrix.md. Equal weights across the SELECTED categories. Final score = sum of category scores ÷ number of categories.

Phase 1: Evidence gathering

For each selected category, run the checks defined in references/category-checks.md. Use grep/ripgrep, AST tools where appropriate, and direct file reads for any flagged file.

Rules during evidence gathering:

• Read the file before recording a finding. Grep matches alone are not evidence.
• If a "violation" has a clear comment explaining why (e.g., # noqa: intentional bypass for legacy migration), check the explanation. If reasonable, skip.
• Track each finding as a tuple: (category, severity, file, line, excerpt, fix_in_one_sentence).

Severity assignment (deterministic):

• P0 (critical): Active security vulnerability, data loss risk, or production outage cause. Examples: hardcoded secrets in committed code, SQL injection, missing authn on a privileged route, infinite retry on user input.
• P1 (high): Reliability or correctness issue likely to bite within months. Examples: unhandled error paths in critical flows, race conditions in shared state, N+1 in a hot path, missing idempotency on a mutation.
• P2 (medium): Maintainability or tech debt issue costing dev time. Examples: dead code blocks >50 LOC, duplicated logic in 3+ places, deprecated API with announced EOL, dependency >2 major versions behind on a critical lib.

Anything below P2 is a nitpick. Drop it.

Phase 2: Scoring

Apply references/scoring-rubric.md exactly. Each category starts at 100 and points are deducted per finding. The rubric specifies max deduction per finding type, so the score has a floor.

Final score = mean of category scores, rounded to nearest integer.

Phase 3: Report generation

Use templates/audit-report-template.md. Required sections, in this order:

1. Project profile (detected types, languages, LOC, threat surface summary)
2. Score (overall + per-category breakdown)
3. P0 findings (must-fix-now, with file:line and one-sentence fix)
4. P1 findings (high-priority, same format)
5. P2 findings (tech debt, same format)
6. Prioritized fix list (top 10 actions in order, estimated effort: S/M/L)
7. What was NOT audited (be explicit about scope limits)

Banned content in the report:

• "Consider..." / "You might want to..." / "It would be nice if..." — replace with imperative actions or drop
• Style opinions
• Praise paragraphs ("overall a well-structured codebase!")
• Generic advice not tied to a specific file:line
• Findings without file:line citations

Phase 4: Self-check before delivery

Before showing the report to the user, verify:

• Every finding has a file:line citation
• Every finding has a one-sentence actionable fix
• No finding is purely stylistic
• Score math is correct (recompute it)
• "What was NOT audited" section is honest about gaps
• Report contains zero hedging words from the banned list above

If any check fails, fix it before delivery.

Reference files

Always read these before starting an audit. They contain the deterministic rules:

• references/category-matrix.md — which categories apply to which project types
• references/category-checks.md — exact checks per category
• references/scoring-rubric.md — point deductions per finding type
• templates/audit-report-template.md — required output structure

Anti-patterns to avoid

• Don't audit dependencies' source code. Stay in the user's code.
• Don't run the code. This is static analysis only unless the user explicitly asks for runtime profiling.
• Don't suggest rewrites. "Rewrite this in Rust" is not actionable feedback.
• Don't pad the report. If a category has zero findings, write "No findings." and move on.
• Don't audit generated files (*.generated.ts, migration files unless they have logic, lockfiles, minified output).