Fable Review

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.

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

The pillars

If git ls-files | cut -d/ -f1-2 | sort -u lists a directory that no pillar's Look-at column names and that holds shipped code, add a pillar for it and say so in the header. If a pillar's Look-at paths do not exist in the tree, drop it and say so; a dropped pillar is not a zero.

Evidence rules

• Cite file.ts:123 for anything the reader would open, and name the symbol next to it. Line numbers rot within hours on an active branch; the symbol is what survives.
• Quote the shortest decisive line of any output. Never paste a log.
• Distinguish confirmed from theoretical. "WKWebView may evict localStorage" with no observed incident is labeled as such, and it ranks below anything a user has actually hit.
• Deliberate simplifications documented in the domain playbook or a ponytail: comment are not findings. Contract text beats rediscovering an invariant from code; a code/contract mismatch is itself a finding, routed to the self-improvement protocol.
• Verify effort estimates against the real site count. "Kill the conditional-pass e2e steps" reads as small and is not: it turns green scenarios red, because they were hiding gaps.