/ratchet-audit

name: ratchet-audit
description: Deep multi-agent audit of the current codebase that ends in an executable artifact — ratchet/AUDIT.md (understanding + findings) and ratchet/BACKLOG.md (prioritized items with evidence, minimal specs, and runnable acceptance criteria, in ratchet:v1 format). Use when the user says "audit this repo", "ratchet audit", "review the codebase and give me a backlog", or before pointing /ratchet-loop at a project for the first time. Read-only: changes no source files.

Ratchet Audit — from codebase to executable backlog

Your output is not a report card; it is **work orders**. Every finding must survive verification down to file:line and arrive with acceptance criteria a later session can actually run. A finding that can't be turned into a checkable item belongs in AUDIT.md's notes, not in the backlog.

Invocation

/ratchet-audit [focus] [--depth quick|standard|deep]

• `focus` — optional: `security`, `performance`, `tests`, `data`, `frontend`, or free text ("multi-tenant isolation"). Default: full sweep.
• `--depth` — `quick` (no subagents, top risks only), `standard` (default), `deep` (more agents, adversarial verification pass).

Phase 1 — Fingerprint the project (yourself, fast)

1. Read the manifests and configs: `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml`, lockfiles, CI workflows, Dockerfiles, env examples, top-level README/CLAUDE.md/CONTRIBUTING. 2. Determine: stack, entry points, how it's tested (**capture the exact commands** — they become Global checks), how it's deployed, and the domain axes that matter (multi-tenant? auth? payments? background jobs?). 3. **Baseline reality check (mandatory).** Run each candidate Global check **cold** — fresh clone semantics: no incremental cache, no dev-server-generated types, the way CI runs it. A check that passes warm but fails cold is a *non-deterministic* check and is worse than useless as a gate (the loop will read a false green). When you find one: (a) pin the Global check to its deterministic form (e.g. `tsc --noEmit --incremental false`, not `tsc --noEmit`), and (b) if the cold run is **red**, that is not a "skip" — it is your **first backlog item**, tagged `[BASELINE]`, because the loop cannot ratchet forward from a red baseline. Never emit a backlog whose own Global checks are red with no `[BASELINE]` item to fix them. 4. Pick audit dimensions by project shape — typical for a web app: **data layer/schema · API surface/authz · business logic/duplication/fragility · tests/CI/ops · frontend/UX debt**. A CLI or library gets different cuts (public API, error handling, packaging, docs). Don't force irrelevant dimensions.

Phase 2 — Fan out (parallel subagents; skip at `--depth quick`)

Launch one read-only exploration agent per dimension, **in parallel**. Each agent's brief must demand:

• Facts with `file:line` citations, never file dumps.
• Explicit separation of **observed** vs **inferred**.
• A ranked list of concrete defects/risks for its dimension, each with: what, where, why it matters, and how one would *prove* it's fixed (this becomes the acceptance criteria seed).
• Counting where it strengthens claims (route totals, models without a tenant column, dead files with zero importers).

Prompts must be self-contained (agents don't see your conversation): include the repo path, the stack fingerprint from Phase 1, and the dimension's specific questions.

Phase 3 — Verify before you write

For every candidate finding: open the cited file yourself and confirm the evidence holds **today**. At `--depth deep`, additionally spawn independent verification agents prompted to **refute** each HIGH/MED finding (each verifier gets only the claim + repo path, not the finder's reasoning); a finding survives only if the refuter fails. Drop or downgrade anything you cannot confirm — the loop downstream will trust your evidence literally, so unverified findings poison everything after them. Severity honestly: HIGH = exploitable/corrupting/money-losing now · MED = will bite under a plausible condition · LOW = debt and drift. Never inflate.

Phase 4 — Write the two artifacts

Create the `ratchet/` directory (respect an existing one: **append/update, never clobber** a BACKLOG.md that has Ledger progress — new items go under new IDs).

**If the existing backlog is v2** (marker `<!-- ratchet:v2 -->`; items carry `Lane:`, state lives in `lanes/<lane>.md`): append items **with** a `Lane:` field — pick the declared lane whose scope contains the item's Evidence/Spec paths; dependency-adding or shared-path items go to the first-declared default lane; if no assignment is defensible, the finding goes to AUDIT.md's "needs definition" list instead. Write each new item's `todo` ledger row into its lane's file, **never** emit `## Ledger`/`## Journal` sections into a v2 backlog, and touch nothing while a lane run is open (a lane journal whose last run marker is `run started` — respect the format's human write windows; if every lane is open, put the items in AUDIT.md and say so). Fresh emission stays v1 below — v2 is opt-in via `/ratchet-backlog migrate` or an explicit user ask.

**`ratchet/AUDIT.md`** — the context: what the project is, architecture, hidden assumptions, what's strong and must be preserved, what's fragile, what remains unclear (say exactly what you couldn't verify — never bluff).

**`ratchet/BACKLOG.md`** — a **fresh** backlog is always `ratchet:v1` (v2's parallel lanes are opt-in, via `/ratchet-backlog migrate` or an explicit user ask; appending to an existing v2 file follows the rule above). The skeleton you must emit (full spec: `docs/backlog-format.md` in the ratchet repo, github.com/afrizzal/ratchet):

# BACKLOG — <project or scope name>
<!-- ratchet:v1 -->

## Global checks
- `<verify command, deterministic form>`

## Items

### SEC-01 — <title> [P0]
- Tags: —                  ← only [RISKY] [OPS] [USER-DECISION] [BASELINE], or —
- Depends: —
- Evidence: path:line