/fable-review

name: fable-review
description: Use when asked for a full codebase review, health check, quality audit, or scorecard of this repo, or for a "fable review" / multi-pillar review whose output another agent will execute. Runs only on Fable. Triggers on "fable review", "review the codebase", "score the repo", "audit code health".

Fable Codebase Review

Overview

A scored, multi-pillar codebase review whose output is a report another agent (Opus) executes without re-deriving anything. The pillars and the report shape come from the first run of this review (issue #217, PR #218, overall 7.5 to 8.1); the rules below are what that run and its two follow-up reviews proved necessary.

**Core principle: every finding was confirmed by reading the file it cites. A grep hit is a lead, not a finding, and a pillar score with no evidence under it is an opinion that does not get a number.**

Second principle: the report is executed by an agent that cannot see this session. Anything a finding leaves implicit - the fix, the verification, the risk, the reason a nearby thing must not change - is work the executor will get wrong.

Preconditions (check both before anything else)

Clean context

The review must start from a clean context. A session that has already done implementation work carries the assumptions it made while working, and it will grade its own output: gates it stopped checking read as green, code it wrote reads as idiomatic, and drift it introduced becomes invisible. Re-running these checks from a fresh context is the point of the review.

If this session already holds prior work - edits, debugging, a long conversation, or anything beyond the invocation itself - **stop** and say:

> This review needs a clean context. Start a fresh session (`/clear`, or > `claude -p "/fable-review"` from a new shell) on Fable, then run > `/fable-review` there.

Pillar agents inherit this: each gets a fresh context and a written brief. Never paste session history into a dispatch.

Model

This review runs on Fable only. Fable's judgment across a whole repository is the deliverable; the orchestrator's model bounds everything under it (see Orchestration in `agents/generic/claude-workflows.md`).

1. Your own system prompt names the model you are running as. 2. If that name is not Fable (model id `claude-fable-5`), **stop immediately**. Read nothing, dispatch nothing, write nothing. 3. Say exactly this and end the turn:

> This review runs on Fable. You are on <model name>. Switch with > `/model` (pick Fable 5), then run `/fable-review` again.

Do not work around the gate: not by dispatching Fable subagents under a different orchestrator, not by "starting the easy parts" first, not by offering a lighter review instead. `.claude/settings.json` pins this repo to Opus by default, so hitting this gate is the normal case, and switching is the user's call.

Procedure

1. **Read the instruction system first.** `AGENTS.md`, `AGENTS.project.md`, every file in `agents/project/` and `agents/generic/`. Pillar 3 scores adherence to those contracts, and the domain playbook lists approaches that already failed here - a review that recommends one of them is worse than no review. 2. **Record scale and state.** File and LOC counts for `app/src/` (prod vs test split), native shells, `docs/`, workflows. Name what you excluded. Record `git status` and `git branch --show-current`; a dirty working tree changes what the executor may commit. 3. **Run the gates bare.** `npm run gates` from `app/`, plus `npx madge --circular` style structural probes as needed. Never pipe a gate into a filter (the pipeline reports the filter's exit status; that shipped a red commit here once). Record raw counts and quote failures verbatim. 4. **Dispatch one read-only agent per pillar, all in one message**, each on Fable (`model: "fable"`). Fill `brief-template.md` (next to this file) once per pillar; the filled template is the whole prompt. Agents read and probe only - no edits, no commits. Stop each agent as soon as its report is verified. 5. **Verify before publishing.** Re-read the cited source for every damning or load-bearing claim yourself. Duplication and dead-code claims are wrong often enough that an unverified one belongs nowhere near a score. A claim you cannot confirm is dropped, not softened. 6. **Score, rank, write.** One decimal per pillar from the rubric below, an overall, then the phased execution plan. Rank by risk reduced per unit of effort, not by pillar order. Before scoring, read the scorecard of the newest `docs/superpowers/analysis/*-fable-review.md`; any pillar moving more than 1.0 from it gets one sentence naming the findings (or fixes) that moved it.

Scoring rubric

Scores come from confirmed findings, not impression. Start at 10 and apply the cap or deduction each row names; the lowest cap wins, then deductions apply below it.

| Condition | Effect | |---|---| | Any confirmed HIGH finding | Cap 7.0 | | Three or more confirmed HIGH | Cap 5.0 | | A gate the pillar relies on is red or advisory-only | Cap 6.0 | | Each confirmed MED | -0.5 | | Each confirmed LOW | -0.2 | | Pillar skipped by instruction, or evidence could not be gathered | No number; write "not assessed" |

Floor is 1.0. Overall is the mean of scored pillars only.

The pillars

| # | Pillar | Scores what | Look at | |---|---|---|---| | 1 | Code clarity | Idiom consistency, unnamed state machines, dead ternaries, IIFE-in-JSX, comments that explain why | Largest components, hooks with paired raw/wrapped setters | | 2 | DRY and reuse | Real cross-file duplication (verified by hand), under-adopted shared components | Page scaffolding, error banners, empty states, control wiring | | 3 | Contract and rule adherence | Every contract in `AGENTS.project.md` (Owns/Path/Never/Gate) plus the AGENTS.md tiers, measured by counts not vibes | `app/src/tests/agents-contracts.test.