| name | review-codebase |
| description | Use to run a whole-system adversarial audit of the current repo across three lenses at once — codebase (defects, incoherences, affordance gaps), docs (drift, structure, coverage), and process (end-to-end workflow dead ends). Dispatches three fresh Claude subagents in parallel, each writing a ranked findings report to docs/audits/, then offers an optional fix pass on CRITICAL findings. Triggers on: review codebase, audit codebase, audit this repo, adversarial audit, codebase audit, docs audit, process audit, fable audit, three reviews, full audit, whole-system review, find everything wrong. |
| user-invocable | true |
Review Codebase — Three-Lens Adversarial Audit
Fires the three Fable adversarial audits — codebase, docs, and process — against the
current repository, all at once. It automates the launcher from
this gist: instead
of fetching the prompts into .prompts/ and pasting a /goal per prompt, the three prompts
are embedded as templates and each is dispatched to its own fresh-context subagent.
Where it sits in the review family:
/code-review, /review-pr — line-level correctness on a diff./spec-review-codex / -local — harden the spec, before code exists./architect-review-pr — completeness & wiring of one finished feature (one subagent)./review-codebase — whole-system audit across three lenses (three subagents). This skill.
Why fresh subagents (the adversarial mechanism). Each audit re-derives its findings from
the code alone, with no memory of how the system was built — the same independence rationale
as /architect-review-pr. Three run in parallel, isolated, so each full-repo audit's raw
output stays out of the main loop (the /fusion panel pattern). No external CLI — subagents
are Claude Agents, so the skill installs anywhere.
Report + optional fix. Each audit is report-first: it writes a ranked, ID'd findings report
to docs/audits/ and returns only a short summary. After the three land, the skill offers a
remediation pass on CRITICAL findings — opt-in, never automatic, never committed.
Flow
Step 0 — Preflight & scope
- In a git repo? Run
git rev-parse --is-inside-work-tree. If it fails, STOP with:
"Not in a git repository — nothing to audit."
- Resolve the date once:
DATE=$(date +%F). Target repo = current working directory.
- Which lenses? Parse the optional argument for
codebase, docs, and/or process
(any subset, space/comma-separated). Default = all three.
Announce the resolved scope in one line, then proceed:
"Auditing <repo> across . Dispatching subagent(s) in parallel."
Step 1 — Dispatch the audits in parallel
For each selected lens, dispatch one fresh subagent via the Agent tool
(subagent_type: general-purpose). Fire them in a single message, one Agent call per lens,
so they run concurrently.
First resolve the templates dir to an absolute path and substitute it into each prompt —
a subagent's Read tool will not expand ${CLAUDE_PLUGIN_ROOT}. Run
echo "${CLAUDE_PLUGIN_ROOT}/skills/review-codebase/templates" in Bash and use the printed
path as <TEMPLATES> below. Each subagent's prompt (substitute <TEMPLATES>,
<KIND> = codebase/docs/process, and <DATE>):
Read <TEMPLATES>/<KIND>-audit.md in full and
execute its instructions to the letter against THIS repository (the current working
directory) — that file is your task spec, not reference to summarize or improve. Stay
strictly within the scope it defines.
Write the full report to docs/audits/<KIND>-audit-<DATE>.md (create the directory if
missing). REPORT-ONLY: make no code change, and do not commit, push, or otherwise touch git
state — the maintainer owns git. Leave the report uncommitted.
Use this severity scale for every finding and in the summary counts: CRITICAL / IMPORTANT /
ADVISORY / MINOR.
Not done until the prompt's Output/stop criteria are met exactly as written. Return ONLY the
short exec summary the prompt specifies (per-severity counts + top 3-5 findings + the report
path) — the full detail lives in the file.
The process audit is empirical: it builds throwaway workspaces under a gitignored dir and may
stub external binaries via PATH shims — that is expected and stays out of the real tree.
Step 2 — Consolidate
Collect the three returned summaries and print one table:
| lens | CRITICAL | IMPORTANT | ADVISORY | MINOR | report |
|---|
| codebase | … | … | … | … | docs/audits/codebase-audit-<DATE>.md |
| docs | … | … | … | … | docs/audits/docs-audit-<DATE>.md |
| process | … | … | … | … | docs/audits/process-audit-<DATE>.md |
Below it, list the top findings each audit surfaced (by ID). If a subagent failed or produced
no report, say so plainly — do not fabricate a summary.
Step 3 — Offer a fix pass (opt-in)
If any audit reported CRITICAL findings, ask:
"N CRITICAL findings across the reports. Want me to fix them now? (Reports and any fixes stay
uncommitted — you own git.)"
- If yes: address CRITICAL findings by cited ID (Cn/Dn/Pn), reading each report for the
file:line and scenario. Leave every change in the working tree uncommitted. One pass —
no fix/re-review convergence loop (that's the spec-review family). Then STOP.
- If no (or no CRITICALs): STOP. The reports are the deliverable.
Never auto-run the fix pass. Never commit — not the reports, not the fixes.
Templates
Embedded under templates/, the source of truth for what each subagent runs:
| File | Lens |
|---|
codebase-audit.md | Defects, incoherences, affordance mismatches, doc drift, DX (IDs C1…). |
docs-audit.md | Doc drift, inverted-pyramid, sizing, missing diagrams, coverage (IDs D1…). |
process-audit.md | End-to-end workflow dead ends, missing transitions, re-run semantics (IDs P1…). |
Ported from the gist above (MIT-spirited author prompts). codebase and docs are verbatim;
process is generalized — the gist's version is written for one specific project (its
ingest/vault/publication lifecycle and pdftotext shims), so the embedded copy keeps the role,
method, hunt categories, and output contract but drops the project-specific context. To re-sync
after the gist changes, re-fetch with
gh gist view 04970a2b8d9cc419de3ba05b9a03db5a -f fable-audit-<kind>.txt -r and reconcile by
hand (keep the process generalization).
What this skill is NOT
- Not a diff review — it audits the whole repo, not a branch's changes. For line-level
correctness on a diff use
/code-review or /review-pr; for one feature's wiring use
/architect-review-pr.
- Not a fix-loop — the fix pass is a single opt-in remediation, not the spec-review family's
converging fix/re-review cycle.
- Not a committer — reports and fixes always land uncommitted; the maintainer owns git.
Deliberate simplifications (ponytail)
- Embed, don't fetch — no network dependency and no
.prompts/ written into the user's
repo. Re-sync is a documented manual step, not runtime machinery.
- One subagent per lens, flat parallel — the three audits are independent; no dependency
graph, no batching, no merge logic beyond concatenating three summaries.
- Fix pass is opt-in and single-pass — no convergence/enumeration-creep machinery. Upgrade
path: add a re-review loop only if fixes prove to regress reports.
- No scripts — the dispatch prompt is composed inline here, like
/architect-review-pr.
