Audit

Audit

Standalone Codex host branch

Claude frontmatter, TLDR, agent teams, dynamic workflows, codex-verifier, and codex-run.ts do not apply in standalone Codex. Keep source inspection read-only. Map with rg --files, rg -n, direct import/caller searches, focused file reads, and the repo's own diagnostics; never claim TLDR ran. Use Context7 only when the user configured that MCP. Otherwise inspect pinned manifests and lockfiles, consult official package documentation through native browsing when available, and label currency or API claims unverified when neither source is reachable. This package does not auto-run unpinned registry MCP packages.

For fan-out, create each new reader with spawn_agent, continue a live reader with send_message, trigger another turn for an idle existing reader with followup_task, wait with wait_agent, and stop its current turn with interrupt_agent only when necessary. Only read-only reviewers may overlap. Writers share the working tree unless the live host explicitly offers isolation, so the main session writes the final report after readers finish; any implementer and test-writer phases must be serialized with non-overlapping ownership.

One skill, eight whole-repo audit modes. Seven of them share a skeleton: read the surface in full (never sample), hunt with explicit categories, and ship a prioritized, executable report or plan set. Six families of question:

• Codebase — one merged audit, two lenses on the same read. The structure lens (ported from Cursor's internal thermo-nuclear-code-quality-review skill, reported by Eric Zakariasson as Cursor's most-used internal skill; formerly this skill's standalone Maintainability mode) asks should this code exist? — 1k-line sprawl, thin wrappers, code-judo deletions, dependency freshness via context7. The behavior lens (adapted from the fable audit goal-spec trio, gist diegomarino/04970a2b8d9cc419de3ba05b9a03db5a; formerly the separate Codebase mode) asks does it do what it promises? — correctness, incoherences, affordance gaps. Merged August 2026: both modes fanned the same whole-repo readers over the same files and shipped near-identical reports, so they now run as one pass with two hunt lists. The July 2026 cc-settings audit ran the behavior lens and produced 28 findings, ~all confirmed and fixed.
• Docs and Process — from the same fable audit trio. Truth and structure of the docs (docs), walkable end-to-end journeys (process). The mechanics that made the July 2026 audit work (stable IDs, CONFIRMED/PLAUSIBLE, concrete failure scenarios, design tensions vs line findings, open questions for the maintainer) are the contract for these modes.
• Performance — asks where is time actually going, measured? Empirical-only: a finding does not exist until a number confirms it. Covers client runtime (via the same Lighthouse protocol /lighthouse uses), bundle and build, server and data, and code-level hot paths, adapting to what the repo actually is (web app vs CLI vs library).
• Threat-Model — adapted from openai/skills security-threat-model (Apache-2.0). Asks what can go wrong, and who would exploit it? — trust boundaries, attacker capability, abuse paths tied to attacker goals, mitigations mapped to components.
• Motion — adapted from emilkowalski/skills improve-animations (MIT). Asks where does animation work have the highest leverage? — purpose/frequency, easing/duration, physicality/origin, interruptibility, performance, accessibility, cohesion, and missed opportunities, turned into self-contained implementation plans rather than a findings report.
• SEO — distilled from shipped Darkroom work (satus PRs #348/#405/#413 and darkroomengineering/website PRs #40/#65, which converged independently on the same architecture). Asks will this site be found, ranked, and cited? — canonical integrity, sitemap reachability, per-content metadata, structured data, and the AEO surfaces (llms.txt, named AI crawlers, machine-view routes) that answer engines read.

Codebase mode's structure lens should push to be ambitious — do not merely identify local cleanup opportunities, actively search for "code judo" moves. Every adversarial mode holds no loyalty to the current design — hunt defects, drift, dead ends, and abuse paths rather than confirm things work.

The eighth mode, Debt, is the odd one out: a mechanical grep that collects SHORTCUT: markers into a ledger. It shares none of the skeleton above and makes no judgement — see Mode: Debt at the end of this file.

Mode Router

The bare phrase "audit the codebase" routes straight to Codebase mode — the merge removed the old maintainability-vs-correctness question, because one pass now carries both lenses.

Trigger phrases by mode:

One remaining ambiguity, Performance vs /lighthouse: a page-speed ask scoped to a URL or a target score ("check page speed on /", "improve web vitals", "get LCP under 2.5s") is /lighthouse — it measures one page and loops fixes until targets are met. A repo-wide ask ("performance audit", "why is the app slow") is this skill's Performance mode — it measures every surface and ships a report. When the phrasing genuinely fits both, ask which the user wants; don't guess.

Debt mode is a mechanical grep — run it standalone or as a cheap first pass before Codebase mode.

When to use vs other review skills

• /review — per-diff Darkroom checklist (TypeScript / React / a11y / perf / security), now including an animation checklist when the diff touches motion. Every change.
• /audit (this skill) — periodic whole-repo audit, eight modes. Codebase mode asks "should this code exist, and does it do what it promises?"; docs and process modes ask whether the docs tell the truth and the journeys walk end-to-end; performance mode asks "where is time actually going, measured?"; threat-model mode asks "what can go wrong, and who would exploit it?"; motion mode asks "where does the animation work have the highest leverage?"; seo mode asks "will this site be found, ranked, and cited?"; debt mode asks "what did we defer on purpose?" Run codebase mode on major version cuts, after extended velocity sprints, before a load-bearing migration. Docs and process modes shine before releases and after feature bursts. Performance mode fits before a launch, after a dependency-heavy sprint, or whenever "the site feels slow" comes up without a number attached. Threat-model mode fits before a security-sensitive launch or a new internet-facing surface. Motion mode fits after a UI-heavy sprint or before a client showcase. SEO mode fits before a site launch and as a first pass on any client marketing/content site.
• /lighthouse — single-page CWV measurement plus a fix-until-targets-met loop. Performance mode delegates its client-runtime measurements to the same Lighthouse protocol and hands findings back to /lighthouse or /refactor for execution; it never duplicates the loop.
• /zero-tech-debt — rework a specific patch to its intended end-state. Not a review — it edits.
• /verify — adversarial check of a single change/claim, not a repo sweep.

A typical sequence: /audit codebase produces findings → engineers cherry-pick the highest-leverage ones → the right executor by finding type: dead code and duplication go to the deslopper agent (auto-removes what's provably dead, stages consolidations for approval), structural rework to /zero-tech-debt or /refactor, client-runtime perf findings to /lighthouse.

Claude Code only (v2.1.154+): standalone Codex skips this tip and the Workflow command below. In Claude, run /effort ultracode before invoking this skill. Whole-repo audits are the canonical shape that benefits from dynamic workflows — phase state lives in the workflow script rather than Claude's context window, individual areas can be reviewed in parallel (up to 16 concurrent), and the run can resume from cached agent results within the session. Dynamic workflows default to a medium size guideline, aiming for fewer than 15 agents (v2.1.219) — it's advisory, not enforced, but a repo with more modules than that is worth raising workflowSizeGuideline for explicitly before the fan-out phase rather than silently exceeding the default.

A ready-made example for codebase mode's structure lens ships at references/nuclear-review.workflow.js (installed to ~/.claude/skills/audit/references/). It is opt-in, not a dependency — the mode works with no Workflow tool. Run it with Workflow({ scriptPath: "~/.claude/skills/audit/references/nuclear-review.workflow.js" }), or copy it into .claude/workflows/. It maps the repo, fans out one structural reviewer per module, audits dependencies, and synthesizes one report. Treat it as a template — adapt its module list, schemas, and phases to the repo at hand rather than running it verbatim.

Shared Contract (Codebase, Docs, Process, Threat-Model, SEO, and Performance modes)

Role. No loyalty to the current design/structure/flows. Act simultaneously as a senior staff engineer, a skeptical first-time consumer, and an adversarial reviewer. Understand deeply enough to challenge, not merely validate.

Method.

• Per area, state how it SHOULD behave, then read (or run) to confirm or refute. Every expectation-vs-reality gap is a finding.
• Every finding needs a concrete scenario: specific inputs/state leading to the wrong or surprising result. No vague "could be improved."
• Mark each finding CONFIRMED (traced or reproduced) or PLAUSIBLE (suspected). Try to disprove yourself first; discard findings that don't survive. (Performance mode tightens this: PLAUSIBLE does not exist there — see its evidence rule.)
• Where something is sound, say so once and move on — spend effort where it isn't.

Cross-model + intent passes. In Claude, run the shared procedures in references/audit-contract.md (§1 Codex cross-model pass via codex-verifier on the finding list, §2 team-knowledge reconciliation). Both are gated and fail open. Standalone Codex never uses the bridge; it may use a fresh native read-only reviewer under the lifecycle above. The one-line invariants: reconcile AFTER findings exist, and a documented decision reclassifies severity, never deletes a finding.

Output. Write the full report to docs/audits/[mode]-audit-YYYY-MM-DD.md (create the dir; leave uncommitted — the maintainer owns git). Structure top-heavy:

1. Summary table: ID | severity | area | one-line issue | file:line | CONFIRMED/PLAUSIBLE.
2. Map (system map / doc map / process state machine — per mode below).
3. Findings by hunt category, severity order. Each: stable ID (H1/M1/L1 by severity, or C/D/P prefix per mode), location, one-line issue, concrete scenario, status, recommended direction.
4. Design tensions: the 3-5 deepest structural issues ("the approach, not a line"), each with the alternative you'd weigh.
5. Open questions: what the artifact alone can't resolve — maintainer answers required.
6. Considered & rejected: candidate findings you investigated and disproved (or reclassified as by-design), each with a one-line reason. This ledger is what stops the next audit from re-litigating them — check it before hunting.

Chat reply = exec summary only: counts by severity + top 3-5 findings + report path.

Optional issue filing. When the maintainer wants findings executable by agents, file each as a GitHub issue (one per finding, severity labels, CONFIRMED/PLAUSIBLE in the body, an epic for the design tensions, question-labeled issues for the open questions). This is how the July 2026 cc-settings remediation ran: issues → parallel fix agents → PRs citing the IDs.

Mode: Codebase

One merged audit, two lenses on one whole-repo read: structure (should this code exist?) and behavior (does it do what it promises?). Rides the Shared Contract above.

Scope

The entire codebase, not the current diff:

• All source modules — application code, libraries, scripts, hooks, configs
• The dependency manifest (package.json + lockfile) — every direct dependency
• Folder structure, module boundaries, top-level architectural surfaces (routes, providers, exported APIs)
• Entry points and real (not documented) execution paths; module contracts, explicit and implied
• Data models, invariants, and where they're enforced vs assumed
• External surfaces (APIs, CLIs, config, env vars, file formats, network calls) and the onboarding path a newcomer would actually follow

Skip vendored code, generated files, and node_modules.

Workflow

Phase 0 — Map the codebase

Establish ground truth before judging anything.

# Top-level structure
fd -t d -d 2 --hidden -E node_modules -E .git -E dist -E build

# File-size distribution (largest first) — find the 1k-line crossings
fd -t f -E node_modules -E .git -E dist -E build \
  -e ts -e tsx -e js -e jsx -e py -e go -e rs \
  -x wc -l {} \; | sort -rn | head -50

# Direct dependency count
jq '.dependencies + .devDependencies | length' package.json

# Direct deps with versions
jq '.dependencies + .devDependencies' package.json

In Claude, if the project uses tldr, prefer it for the call graph + dead-code pass. Standalone Codex skips these commands and uses the native searches in its host branch:

tldr arch .
tldr dead . --entry-points "main,test_"

If dead returns unsupported-by-native-engine (the default engine does not implement it), say the dead-code pass did not run — do not record "no dead code" as a finding. An empty result from dead or impact is not evidence; confirm with Grep before acting on it.

If the opt-in tldr-code CLI is installed (~/.claude/code-intel/tldr-code/0.4.0/tldr — see docs/tldr-cheatsheet.md), prefer it for the dead-code pass instead:

~/.claude/code-intel/tldr-code/0.4.0/tldr dead . --lang typescript

It exits 0 even on errors — never trust its exit code. Check that stdout parses as JSON and that functions_analyzed > 0; non-JSON stdout or functions_analyzed: 0 means the scan did not run and must be reported as "scan unavailable", never as "no dead code". dead_functions from tldr-code is ADVISORY ONLY — confirm every candidate with Grep before recording it as a finding. Its MCP path (tldr-mcp, not used here) was measured reporting live symbols as dead code; the CLI was measured accurate, which is why it's used here instead.

When the project depends on deslop-cli (check package.json — it's the same advisory probe /proof-of-work runs), add it as a second dead-code signal: npx deslop-cli. Same rule as tldr-code: advisory only, Grep-confirm every candidate. Two scanners agreeing upgrades conviction; either one alone still needs confirmation.

Phase 1 — Dependency audit (Context7 when configured)

For each direct dependency in package.json, use the context7 MCP server to verify when it is configured. Standalone Codex otherwise uses the native/manual fallback in its host branch and does not execute an unpinned registry MCP:

1. Currency — is the installed version current, or stale? Note major-version gaps.
2. Usage quality — is the codebase using the dependency in the way the maintainers currently recommend? Old APIs, deprecated patterns, missing newer affordances?
3. Necessity — could it be replaced by a platform built-in, an existing canonical helper, or a smaller dependency?
4. Overlap — does it duplicate the role of another dependency? (Two date libraries, two state managers, two HTTP clients.)
5. Footprint cost — for any dependency contributing >50KB to the client bundle, is the usage scope worth the cost? Could it be code-split, lazy-loaded, or replaced?

Use context7 in two steps per dependency:

mcp__context7__resolve-library-id { libraryName: "<package>", query: "<what we use it for>" }
mcp__context7__query-docs { libraryId: "<resolved id>", query: "current recommended usage vs <pattern we use>" }

Cap context7 calls at 3 per dependency (per the server's own guidance). Batch the audit: pick the top 10–20 by either bundle weight or surface-area coverage rather than auditing every transitive dep.

Output for each flagged dep: current version → recommended version, deprecated APIs in use, suggested fix.

Phase 2 — The hunt, both lenses

Walk the largest files first, then the modules with the most outbound dependencies, then the entry points. Apply both lists to every meaningful surface in one pass.

Structure lens — non-negotiable standards:

0. Be ambitious about structural simplification. Do not stop at "this could be a bit cleaner." Look for reframings that make whole branches, helpers, modes, conditionals, or layers disappear entirely. Assume there is often a "code judo" move available — a re-organization that uses the existing architecture more effectively and makes the surface dramatically simpler. Prefer the solution that feels inevitable in hindsight; if you see a path to delete complexity rather than rearrange it, push hard for that path.
1. Flag every file over 1k lines. A strong code-quality smell by default; prefer extracting helpers, subcomponents, or modules. Waive only for a compelling structural reason with the file still clearly organized.
2. Do not tolerate spaghetti. Ad-hoc conditionals, scattered special cases, one-off branches in otherwise cohesive flows — a design problem, not a stylistic nit. Push logic into a dedicated abstraction, helper, state machine, or module instead of tangling existing paths.
3. Bias toward cleaning the design, not preserving working code. If behavior can stay the same while structure gets meaningfully cleaner, push for the cleaner version. Prefer simplifications that remove moving pieces over refactors that spread the same complexity around.
4. Prefer direct, boring code over hacky or magical code. Flag thin abstractions, identity wrappers, pass-through helpers, and generic mechanisms that hide simple data-shape assumptions.
5. Push hard on type and boundary cleanliness. Question unnecessary optionality, unknown, any, cast-heavy code, and silent fallbacks papering over unclear invariants; prefer explicit typed models and shared contracts.
6. Keep logic in the canonical layer and reuse existing helpers. Call out feature logic leaking into shared paths, details leaking through APIs, and bespoke one-offs where a canonical utility exists.
7. Treat unnecessary sequential orchestration and non-atomic updates as design smells. Serialized-for-no-reason work and updates that can leave state half-applied — flag both without over-indexing on micro-optimizations.
8. Dependencies must be current and well-used. Flag deprecated majors, superseded usage patterns, role-duplicating deps, disproportionate footprints, and deps a platform primitive could replace.

Behavior lens — hunt categories:

1. Correctness — logic errors, races, off-by-one, unhandled edges, silently swallowed failures, wrong error propagation.
2. Alternative/unintended paths — second call? concurrent calls? empty/null/huge input? partial failure mid-op? retries? the "holding it wrong" path?
3. Incoherences — names that lie about behavior, two modules solving one problem differently, config honored here and ignored there, duplicated sources of truth that can drift, dead code, contradictory defaults.
4. Affordance mismatches — "I expected to do X this way but can't, or it does something else." Where does the API shape promise a capability the code doesn't deliver? Where is the easy path also the dangerous one?
5. Missing functionality — what a reasonable user expects (validation, idempotency, cleanup, observability, cancellation, timeouts) but is absent.
6. Boundary and safety — leaky abstractions, invariants in the wrong layer, unvalidated input crossing a boundary; injection, path traversal, unbounded growth, resource leaks, missing authz, exposed secrets — only where real.
7. Documentation — README/docstrings/comments that are wrong, stale, or contradict the code; undocumented public behavior/params/errors/side effects; examples that wouldn't run.
8. Developer experience — can a newcomer build, run, test, and debug from the docs alone? Confusing errors, silent misconfig, setup footguns.

Phase 2b — Claude-only cross-model structural pass (when the Codex bridge is available)

Standalone Codex skips this phase. In Claude, run the shared cross-model procedure (references/audit-contract.md §1) with this mode's audit prompt:

bun "$HOME/.claude/src/scripts/codex-run.ts" ask "Audit this repository for structural problems: files over ~1000 lines, thin wrappers that don't earn their keep, logic leaked across boundaries, and duplicated abstractions. Walk the largest files and the modules with the most outbound dependencies first. Report the highest-leverage 'code judo' restructurings — ones that delete whole branches rather than rearrange them — ordered by conviction."

Fold Codex's findings into Phase 3 per the contract: convergence = high-conviction, divergence noted not dropped, gated and fails open.

Phase 2c — team-knowledge reconciliation (when the corpus is reachable)

Phases 2 and 2b judge structure intent-blind, so deliberate design reads as debt. Run the shared reconciliation procedure — references/audit-contract.md §2: generate findings blind FIRST, then cross-reference the corpus; a documented decision reclassifies severity, never suppresses a finding; gated, fails open.

SHORTCUT: markers (AGENTS.md Laziness Ladder) get the same treatment as team-knowledge notes: a marked deferral is a documented decision, not ordinary debt — cite the marker instead of re-litigating it, and escalate only if its stated upgrade trigger has actually fired. Debt mode owns the full ledger; this mode just respects it.

Phase 3 — Synthesis

Produce the Shared Contract report, with two mode-specific additions: open with a one-line verdict — CLEAN / NEEDS RESTRUCTURING / NEEDS MAJOR REWORK — and lead the findings with a Code-Judo Opportunities section (dramatic simplifications: what to delete, not just polish). The map section includes an "expectation gaps" list: short "expected X, found Y" entries for affordance/docs/DX. Prioritize ruthlessly — a smaller number of high-conviction findings beats a long list; do not flood the report with nits when larger structural issues exist.

Severity ordering within the report: structural regressions and missed code-judo moves first, then correctness/incoherence findings, then dependency staleness with material impact, then boundary/type-contract problems, then file-size and legibility concerns.

Phase 4 — Documentation updates (after fixes land)

An audit that produces fixes but leaves the docs stale is half-done. Whenever findings from this mode turn into code changes, the same pass must touch the docs that describe them. If you only produce the report (no fixes in this session), skip this phase — but flag it for whoever applies the fixes.

For each commit that lands from the audit, update the docs in scope for the change:

Rules for the doc pass:

• One [Unreleased] entry per landed commit, or one consolidated entry if multiple commits ship together. Don't leave audit-driven refactors anonymous in git history.
• Skill / agent / rule counts must match reality. If you added or removed one, update every reference (MANUAL.md intro, CLAUDE.md, CLAUDE-FULL.md).
• One short paragraph per entry, naming the file(s) changed and the why. The global Action-First rules (installed CLAUDE.md) apply to doc artifacts too — no padding, no victory laps.
• Regenerate derived docs. If you changed a zod schema in src/schemas/, run bun run schemas:emit and commit the resulting schemas/*.schema.json diff alongside the source change.
• Update MANUAL.md triggers tables when a skill's invocation phrasing changes or when a new skill goes in.

Verify the doc pass landed correctly before finishing:

bun run lint:skills            # frontmatter sanity
bun run schemas:check          # derived schemas in sync with sources
git diff --stat HEAD~N HEAD    # confirm doc files are in the diff

Preferred Remedies

• Delete a whole layer of indirection rather than polishing it.
• Reframe the state model so conditionals disappear instead of getting centralized.
• Change the ownership boundary so a feature becomes a natural extension of an existing abstraction.
• Turn special-case logic into a simpler default flow with fewer exceptions.
• Split a large file into smaller focused modules; extract helpers or pure functions.
• Replace condition chains with a typed model or explicit dispatcher; make type boundaries explicit so control flow gets simpler.
• Separate orchestration from business logic; collapse duplicate branches into one clearer flow.
• Delete wrappers that do not meaningfully clarify the API; reuse the existing canonical helper instead of a near-duplicate.
• Move logic to the package/module/layer that already owns the concept.
• Parallelize independent work when that also simplifies the orchestration; restructure related updates into a more atomic flow.
• Upgrade dependencies to the current major and adopt the modern API; replace a redundant dependency with the one already in the project, or with the platform built-in.

Do not be satisfied with "maybe rename this" feedback when the real issue is structural.

Review Tone

Direct, serious, demanding about quality. Not rude, but do not soften major issues into mild suggestions. If the codebase is messier than its features warrant, say so clearly. If a path to a dramatic simplification was missed, say that too.

Approval Bar

A codebase passes this mode when:

• No file exceeds 1000 lines without an explicit justification.
• No obvious code-judo move is sitting on the table.
• No spaghetti special-casing in shared flows; no thin wrappers or identity abstractions.
• No casts / any / unknown papering over an unclear invariant; no architecture-boundary leaks or duplicated canonical helpers.
• No CONFIRMED correctness, incoherence, or affordance finding left unaddressed or unacknowledged.
• All direct dependencies are within one major of current, used in their maintainer-recommended modern form, with no two duplicating roles.

If any of those fail, the report must include explicit, actionable feedback and push for the cleaner shape.

Attribution

Structure lens ported from cursor/plugins/cursor-team-kit/skills/thermo-nuclear-code-quality-review (whole-codebase scope and the context7 dependency audit are cc-settings additions). Behavior lens adapted from the fable audit goal-spec trio (gist diegomarino/04970a2b8d9cc419de3ba05b9a03db5a).

Mode: Docs

Audit documentation as a first-class artifact: does it tell the truth about the code, lead with what matters, size documents so detail can breathe, and draw processes instead of narrating them?

Role additions: a docs lead who owns information architecture; a newcomer with only the docs and a terminal; a returning maintainer hunting one fact; an autonomous agent using the docs as its only spec.

Scope. Every reader-facing surface in full: README, docs/, ADRs, CONTRIBUTING/onboarding, public docstrings, CLI help, config comments, example scripts, every diagram (source + rendered). Build the current doc map: what exists, what it claims to cover, who it's for, how a reader finds it.

Hunt for:

1. Drift/inaccuracy (primary) — any claim the code no longer honors: renamed/removed commands, flags, env vars, paths, defaults; examples that don't run; output samples that don't match. And the inverse: real public behavior no document mentions.
2. Inverted-pyramid violations — docs that bury the point. Each doc should open with "what this is / when you'd reach for it" plus the 20% answering 80% of questions; reference tables and rationale at the end.
3. Sizing/decomposition — documents where concerns collide: recommend the split (sections, names, back-links). Also scattered fragments that should merge.
4. Architecture as drawn process — flow/lifecycle/interaction explained in prose that a diagram would carry better. Prefer Mermaid: flowchart for control flow, sequence for cross-component calls, stateDiagram for lifecycles.
5. Usefulness/audience fit — does each doc serve a real reader task? Are tutorial/how-to/reference/explanation modes mixed to nobody's benefit? Does it answer "why"?
6. Coverage — public surfaces with no docs; missing troubleshooting/runbook; non-obvious decisions with no ADR.
7. Single source of truth — the same fact in N places that will drift; pick the canonical home, link the rest.
8. Findability — can a reader route to the right doc without knowing where it lives? Missing index, orphans, dead cross-links.

Method addition: for every accuracy claim, check against reality — run the example, confirm the flag exists, diff the sample output. CONFIRMED means verified against code or a run.

Extra output sections: doc map current-vs-proposed (proposed tree = purpose + audience per doc + the splits/merges, executable directly); drift-verification list (finding + exact check run + result); diagram backlog (draft actual Mermaid for the top 3-5, naming target doc + location); missing-docs backlog prioritized by unblocking value.

Mode: Process

Audit end-to-end workflows — not lines of code, but whether the processes the product promises compose into complete, walkable journeys. Find holes, dead ends, missing transitions, and steps where a user or agent gets stranded.

Role. Walk every documented journey twice: once as a first-time human following only the docs, once as an autonomous agent chaining commands via exit codes and JSON.

Scope. Enumerate the product's documented journeys (onboarding/install, the core lifecycle(s), review/approve loops, publish/deploy, cleanup) and walk each empirically in throwaway workspaces under a gitignored scratch dir — never against real state. Fake heavyweight external tools with PATH shims where needed.

Hunt for:

1. Dead ends — states with no exit command, fixable only by hand-editing files.
2. Missing processes — steps the docs promise that no command implements.
3. Re-run/second-call semantics — every mutating command run twice, out of order, and against a half-completed prior run. Idempotency AND exit codes.
4. Partial failure — kill mid-operation, unwritable targets, collisions with pre-existing artifacts.
5. Agent ergonomics — can an agent distinguish "my operation failed" from "unrelated warning elsewhere"? JSON contract stability, help text vs actual flags, error parseability.
6. Docs/process drift — walk the quickstart/process docs command-by-command against reality.
7. Concurrency — two invocations against the same workspace.
8. Cross-process coherence — enumerate every state a record/artifact can occupy across subsystems and check a command moves each state forward.

Map section: the real per-record state machine — states, transitions, owning command; mark unreachable states and absorbing dead ends. If a prior audit was remediated, start by empirically verifying those fixes hold through full workflows (regressions and partial fixes are in scope; re-auditing code style is not).

Method addition: every finding needs the exact command sequence to reproduce and the resulting state/output. CONFIRMED means reproduced, not traced.

Mode: Performance

Whole-repo performance audit with one governing rule: a finding does not exist until a number confirms it. Rides the Shared Contract's report shape, with the evidence rule below overriding its CONFIRMED/PLAUSIBLE split — this mode has no PLAUSIBLE tier.

Role. A performance engineer who does not believe anything until it's measured; a user on a mid-range phone on 4G; a CI bot billing by the build-minute.

Evidence rule (the mode's spine)

• Empirical only. Source reading generates hypotheses, never findings. A hypothesis becomes a finding only when a measurement confirms it — a profile, a benchmark, a timed curl, analyzer output, a Lighthouse run.
• Every finding ships its number and the command that produced it, so any reader can re-run it. The collected commands double as the regression harness for whoever applies fixes.
• Unmeasurable hypotheses (the surface can't be exercised, the tool isn't available) go to an explicit Unmeasured candidates appendix: ungraded, uncounted, absent from the summary table. They are leads for a future audit, not findings.
• Nothing runnable at all (can't build, can't serve, no bench entry points)? Stop. Report "not measurable" with the list of what would need to exist to measure — never degrade into a speculative report.
• No invented numbers, no estimated savings. A fix's benefit is measured after it lands by re-running the logged command — never predicted in the report (AGENTS.md "no savings against a run that never happened").

Playbook and harnesses. references/performance-playbook.md is the measured fix ladder for mobile and slow-connection load (images, unused client code, inline CSS, per-route CSS chunking, font subsetting with unicode-range, platform elements over client widgets, WebGL gated on the renderer string) with the artifacts to discard first and the traps met on the way. references/net-capture.mjs records a cold load under emulated Slow 3G / 3G with 4x CPU (requests, bytes by type, TTFB/FCP/LCP/load); references/bundle-attribution.py attributes a route's shipped JS to packages and app directories from source maps. Both are the Phase 1 commands for a web app; copy them into the repo's audit folder so the numbers stay reproducible there.

Measurement hygiene: ≥3 runs per number, report median + spread; production builds only (next dev skips optimization paths and lies); label cold vs warm; same machine for any two numbers you compare; record the exact command next to every number.

Phase 0 — What's runnable

Detect the repo's shape and build the measurement plan before measuring anything:

• Web app — can you next build && next start (or the framework's equivalent)? Which routes matter most (traffic order if analytics are known, else: home, top nav destinations, heaviest template)?
• Server/API — can you start it locally and hit endpoints? Is there query logging to count round-trips?
• CLI/library — what are the entry points worth timing? (Startup, the hot command, the public API's hot function.)
• The build itself — always measurable: full build wall-time, test-suite wall-time, CI duration from recent run logs.

The plan lists each surface, the measurement command, and the budget or leverage anchor it will be graded against. Surfaces the repo doesn't have (no client? no client-runtime section) are marked not-applicable, not skipped silently.

Phase 1 — Baseline measurements

One pass per applicable surface; every number goes into the Measurement Log.

1. Client runtime — delegate to the same Lighthouse protocol /lighthouse uses (3 mobile + 3 desktop runs, averaged) against the production build, per key route. Collect LCP, INP (or TBT as lab proxy), CLS, plus long-task totals from the traces.
2. Bundle & build — the framework's build output for per-route first-load JS; a bundle analyzer pass for composition (which deps dominate); build wall-time via hyperfine 'bun run build' (or 3 timed runs, median, when hyperfine is absent).
3. Server & data — timed requests (curl -w '%{time_starttransfer} %{time_total}') against the local production serve, per key endpoint; query counts per request from logs to catch N+1s; request logs or Server-Timing headers to expose waterfalls.
4. Hot paths (code-level) — CPU profile the heaviest flow (node --cpu-prof / bun's inspector / React Profiler for render counts), or micro-benchmark a suspect function with hyperfine or the test runner's bench support.

Phase 2 — Hypothesis sweep (static, generates no findings)

Now read source for suspect patterns, each recorded as a hypothesis with the measurement that would confirm it: sequential awaits on independent work → time the flow before/after in a scratch branch, or profile the waterfall; N+1-shaped data access → query count per request; heavyweight imports in client components → analyzer composition; missing dynamic() splits → per-route first-load JS; sync I/O or allocation in loops → micro-benchmark; unmemoized components in hot trees → React Profiler render counts. Cross-check against rules/performance.md and rules/react-perf.md for the patterns Darkroom already bans. When the project has tldr, use the call graph to target the sweep — high fan-in hubs from tldr calls/tldr arch are the hot-path candidates worth profiling first — instead of grepping blind.

Phase 3 — Confirm or discard

Run the confirming measurement for every hypothesis:

• Confirmed with a number → finding, graded below.
• Measured and fine → Considered & Rejected, with the number (this is the valuable half — it stops the next audit re-measuring it).
• Couldn't be measured → Unmeasured candidates appendix.

Severity — two anchors, both empirical

Budgets (for surfaces with a named limit). Budget sources in priority order: a budget file already in the repo (lighthouserc, budgets.json, perf config) → the budgets table in ~/.claude/docs/performance-reference.md (Darkroom installs; summary in rules/performance.md) → these defaults: LCP ≤

…(truncated)