Project Truth Audit

Audit a whole repo or project from the root before claims or edits. Use when the user asks for a project truth audit, whole-repo reality audit, stop-and-think pass, reality check, contract drift audit, stale docs audit, half-finished implementation audit, unsupported-claims audit, or asks what is wrong with the actual system shape.

Use this when the user wants the agent to stop, inspect the actual project, and compare what the system claims with what the code, docs, tests, install paths, release paths, and live probes actually prove.

This is an audit mode, not a normal module map. It should catch bad assumptions, nearby-file tunnel vision, stale documentation, optional-vs-required drift, half-implemented contracts, and claims of success without proof.

Contract

The audit must report current project truth from the requested scope. Memory, handoffs, comments, README claims, old reports, and previous-agent summaries are hints only. Current files, current command output, current tests, current repo state, and current live probes win.

Do not edit files during the audit unless the user explicitly asked for fixes. If fixes are requested, audit first, then change only the named scope after you can name the affected files and the proof command for the fix.

Workflow

1. Resolve the requested root and scope.

   • Read project rules first: AGENTS.md, CLAUDE.md, CONTEXT.md, or any path-specific instruction files that apply.
   • Keep named paths, products, branches, refs, and only constraints binding.
   • If the requested root is unclear or missing, stop and report that before substituting another project.

2. Build the truth map from the root, not just the mentioned file.

   • Inventory top-level structure with rg --files, find, package manifests, build configs, CI configs, docs, scripts, tests, and generated-output boundaries.
   • Identify the project's claims: README, install docs, release docs, website copy, public package metadata, examples, comments, and handoff notes.
   • Identify enforcement: runtime entrypoints, config loading, validation, API boundaries, migrations, build scripts, deploy scripts, and error paths.
   • Identify proof: unit tests, integration tests, smoke tests, CI workflows, local commands, packaged artifacts, live endpoints, or registry checks.

3. Trace high-risk seams one level beyond the obvious file.

   • Entry points and caller/callee paths.
   • Required vs optional config and environment variables.
   • Install, packaging, release, deployment, and generated artifacts.
   • Auth, secrets, payments, network calls, database writes, file deletion, migrations, and other irreversible side effects.
   • Fallbacks, TODOs, placeholders, dead scripts, duplicate implementations, stale docs, and unchecked assumptions.

4. Compare claim, enforcement, and proof.

   • Mark each important contract as verified, partial, stale, contradicted, or unknown.
   • Treat passing tests as proof only for the behavior they actually exercise.
   • Treat docs and comments as claims, not proof.
   • Separate source-repo truth from installable artifact, deployed site, published package, registry, or live-service truth.

5. Report before fixing.

   • Findings come first, ordered by severity and grounded in file paths, line numbers, commands, or live-probe output.
   • Include the smallest proof command that would validate each fix.
   • If the user asked for implementation after the audit, state the planned edit scope before patching.

Output Format

Return:

• Scope: requested root, branch/ref if relevant, and any exclusions.
• Read: important docs, configs, entrypoints, tests, scripts, and artifacts inspected.
• Proof: commands or live probes run, with pass/fail/blocked status.
• Findings: severity-ordered issues. For each issue include claim, actual, impact, evidence, and fix/proof.
• Truth table: important claims with claim, enforcement, proof, and status.
• Unknowns: what could not be verified and why.
• Next: the smallest safe fix or proof step, if any.

Credit

Inspired by Matt Pocock-style agent skills and the /zoom-out idea, then extended into a stricter whole-project truth audit that compares claims, enforcement, and proof.

Anti-Patterns

• Do not summarize only the nearby module and call it whole-project context.
• Do not trust memory, handoffs, generated reports, or README language without checking current files or commands.
• Do not call something ready, final, rebuilt, reviewed, or verified without fresh proof.
• Do not broaden scope into unrelated repos, cleanup, rewrites, or tool installation.
• Do not collapse partial, stale, unknown, and contradicted into a single vague "needs work" bucket.
• Do not hand-edit built artifacts and present them as source truth.