codebase-audit

Start by establishing a runnable baseline with ruff check and the full pytest suite, then inventory and read every target file. Scan for smell categories, verify apparent bugs with the AST parser rather than eyeballing, and report findings grouped HIGH/MED/LOW with file:line and a minimal restructure.

Extract every load-bearing claim from the docs (signatures, constants, config keys, semantic claims), then batch-verify each against the source clone with grep. Every finding needs dual citations: code path:line plus the doc line. Watch especially for inverted if/elif branches described in prose.

A collection error in any test_*.py aborts just that module while pytest still reports the rest as passed, so a green count can hide a silently dropped module. Always grep the full output for 'ERROR collecting' and confirm specific modules actually execute before trusting the number.

Use the loop after a refactor or migration when you want independent verification. Dispatch parallel read-only agents with vague briefs and re-sliced file scopes each round, apply worthwhile findings, re-run the suite, and stop only when a full round returns nothing actionable.

Read-only recon diagnoses and ranks issues but never fixes them; implementation belongs to a separate cleanup step. It can also produce false positives if findings are not verified against the parser and the test suite, since tests often prove a flagged bug is intended behavior.