codebase-audit

Codebase audit

Assess the repository's current state rather than a branch diff. Produce a truthful coverage map, actionable findings, and coherent remediation batches.

Modes and boundaries

The audit is non-remediating by default. It may run safe local tests, builds, servers, browser flows, disposable repros, isolated test data, and temporary artifacts, but it must not edit repository content or create persistent or externally visible side effects. Clean up disposable artifacts and report anything retained.

subagents is an additive execution input. Without it, do not delegate any part of the audit.

A request to save JSON authorizes only the named findings artifact; it does not authorize remediation. Read references/findings-json.md only when JSON output is requested.

There is no fix-all mode. After reporting, offer remediation batches. A fix follow-up begins only when the user selects a coherent batch or finding IDs. It authorizes focused local edits and validation on a focused branch, not commits, pushes, publication, issue creation, deployments, or shared-state mutation.

Map before judging

1. Read applicable project instructions, vision and product documentation, current source, tests, configuration, lockfiles, generated interfaces, completion contracts, packaging, and deployment definitions.
2. Map user-visible capabilities, entry points, modules, trust boundaries, data and state flows, background work, external dependencies, tests, tooling, and operational paths.
3. Choose perspectives from the actual codebase:
   • always cover behavior, correctness, architecture and consistency, simplification, self-documentation, test value, and operations;
   • add UI/UX and accessibility when interfaces exist;
   • add security and adversarial-input analysis at trust boundaries;
   • add persistence, migration, transaction, concurrency, and idempotency analysis for stateful paths;
   • add API, CLI, library, packaging, compatibility, deployment, rollback, observability, and performance analysis only where those surfaces exist.
4. For a shallow subsystem, trace its complete path and direct interactions. For a layered codebase, partition work by capability and perspective so later areas do not receive progressively thinner analysis.
5. Build a bounded churn map from repository history. Rank frequently changed files, then inspect function, method, class, or module history where symbols are reliable. Use the repository's declared churn window or 90 days when none exists. Prefer its code-health tool; otherwise use Git file history and git log -L for stable symbols. Follow renames; state the window, touch count, and line churn, and label file-level fallback.