Project Truth Audit

SKILL.md

---
name: project-truth-audit
description: 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.
---

# Project Truth Audit

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.