/review

Seven phases. Each reads files and writes files under one run directory. No phase reads another phase's chat reply. Spec: docs/superpowers/specs/2026-10-28-review-chain-design.md.

Run directory

Where the notes file goes. Resolve the destination in this order, and state which one you used when you hand the review over:

1. $HUD_ROOT/projects/<project>/prs/PR-N/review.md when HUD_ROOT resolves — the env var if set, else ~/hud if that directory exists. This is the default, and it is the HUD consolidation rule applied: a review artifact is a note, and notes live in exactly one tree — the one that is backed up, indexed, and searchable months later when you need the matrix again. The PR folder is the PR's one home: a second review of the same PR replaces review.md rather than adding a sibling, and anything else about that PR (reply drafts, follow-up notes) goes in the same folder, not in notes/.
2. /tmp/<owner>-<repo>-review/PR-N/review.md only when no HUD tree resolves. A scratch path is an honest "this is not being kept"; say so rather than letting the author assume it was filed somewhere.

Two destinations are wrong regardless of which branch you took. Never a browser's download directory — it is unbacked-up, unindexed, and invisible to every later search, so work content put there is work content lost. Never inside the repo under review, which is how a private review note becomes a commit. And never inside the agents/skills repo either: that repo holds the review machinery, not the output of running it.

The run directory is the raw/ beside that note ($HUD_ROOT/projects/<project>/prs/PR-N/raw/), or /tmp/review/<owner>-<repo>-N/ when no HUD tree resolves. evidence/ and work/ live under it; the rendered artifact is written to the note path at the end of phase 6. It sits under raw/ so the HUD lists those files without opening them as notes.

Resolve <project> as: an existing $HUD_ROOT/projects/<x>/ whose CONTEXT.md names a touched path or the repo; else the project the operator stated; else an existing $HUD_ROOT/projects/<x>/ with no CONTEXT.md whose name equals a top-level directory the change touches ({{CONTEXT}} is then (none), and say in the hand-over that the project has no context file); else inbox.

Phase 1 — Evidence (script, no model)

SKILL=~/.claude/skills/review
node $SKILL/scripts/state.mjs <run> init --pending pr=<owner/repo#N> mode=<light|default|deep|fast>
bash $SKILL/scripts/review-evidence.sh --pr <owner/repo#N> --repo-dir <local clone> --out <run>
jq -r '.probes[] | "\(.status)\t\(.name)"' <run>/evidence/manifest.json

--repo-dir is the reviewer's trusted clone: the repo-local pack file and CODEOWNERS are both read at its BASE ref, never from the PR worktree, and the script writes evidence/manifest.sha256 from a timestamp-free hash so a replay can tell whether the evidence moved.

init --pending goes first, so the run's HUD row appears at dispatch and stays visible while evidence runs (about a minute). It records the session that owns the run, which is how a reader tells a live run from a dead one (see Run state).

Every new invocation of /review passes --new right after --pending (init --pending --new pr=...). When <run> holds a run that ended, this starts the next review and packs the old log, evidence/, work/ and review.md into raw/runs/<stamp>.tar.gz, with one line in raw/runs/history.jsonl that render.mjs turns into the note's History section. Without it, the same arguments read as a replay of the ended run and nothing moves, so the new readers would merge the old run's decision files. Leave --new off only when repeating a call within the same invocation.

Read the manifest before anything else. Every UNAVAILABLE row becomes a ledger question in phase 2. Do not re-fetch what the script fetched.

Authorship: compare pr/context.json's author login to gh api user --jq .login. Record own or peer for phase 6; tell no reader.

Then record the evidence in the run's state file, which the HUD reviews panel reads:

node $SKILL/scripts/state.mjs <run> init mode=<light|default|deep>

Pass viewer=<login> if you already ran gh api user; otherwise init runs it. With pr/context.json present the file also carries review_state: authorship, the viewer's latest review, the latest review per human, bot reviews (by flag or login pattern), and how many unresolved threads wait on the viewer versus the author. Every later phase starts with node $SKILL/scripts/state.mjs <run> phase <name> and, once its file is written, ends with node $SKILL/scripts/state.mjs <run> output <name> (questions, settle, refute, triage, teach); phase 6 ends with finish, Post with posted. state.json is a progress file, not evidence: no phase reads it.

Mode

--light, default, --deep. Auto-light: after phase 1, if packs.json matched only docs-only, or git/files lists 3 or fewer files and none ends in .go or .tf, run light unless --deep was given; say so in the hand-over. Pass the resolved mode to state.mjs init.

Light skips refute and triage, so the orchestrator writes their two files itself, as pass-throughs, and the gates run unchanged:

• work/triage.md: header ## Triage — N candidates in, N dispositions out where N is the line count of work/candidates.md; the skill's table (| # | Candidate (one line) | Disposition | Evidence / reason |), one row per candidate in order, disposition question (light), the last cell the candidate's citing ledger row (row N); then the counted footer (**Confirmed: N. Dropped: 0. Already raised: 0. Already addressed: 0. Revised: 0.**).
• work/findings.json: every candidate as {"tag":"Question", "title": <candidate text>, "file_line": <from the row's decision, or "?">, "blast": "not assessed (light)", "rows":[N], "claims":[<ids in claims.jsonl with that row>]}.

No model is dispatched for either file. A light run can never produce a Blocking finding; if a candidate reads like one, rerun without --light.

--fast is a first look, not a review: phases 1–3 and the early signal run, then the orchestrator stops. It writes work/summary.md with the one line **Verdict** PRELIMINARY — <N> early signal(s), <M> candidate(s) unrefuted (N from early.json, M the line count of candidates.md) and a TL;DR that says refute and triage did not run; the same pass-through triage.md as light with disposition question (fast); findings.json with every candidate tagged Question and blast not assessed (fast); then renders, runs check.mjs and state.mjs finish. Pass mode=fast to state.mjs init at phase 1; finish reads PRELIMINARY from the summary, so the HUD row shows fast and PRELIMINARY. check.mjs prints a fourth line, fast: PRELIMINARY — not postable, and exits 1 for any run whose state says fast or whose summary verdict is PRELIMINARY, even when the three gates pass: a fast artifact can never be posted, and --post with --fast stops at that line. Never use it for an approval; its only output worth acting on is the early signal, and every other candidate on it is unrefuted.

Phase 2 — Questions (one sub-agent)

state.mjs <run> phase questions. Dispatch one general-purpose agent with prompts/questions.md, substituting {{EVIDENCE}}, {{WORK}}, {{MAX_QUESTIONS}} and {{THREADS}}. {{MAX_QUESTIONS}} is 8 under --light, 14 by default; under --deep delete the "Ask at most {{MAX_QUESTIONS}} questions;" clause instead, so the count is unbounded. The cap is a budget, not a target, and UNAVAILABLE rows count toward it.

{{THREADS}} is (none) unless --engage. Under --engage, build it from pr/context.json with no model: one line per thread in .threads.items[] whose state is unresolved (- thread <path>:<line> — <first line of the first comment body>), then one per .reviews.items[] with kind review and a non-empty body (- review by <author> (<state>) — <first line of body>). An empty body is the review GitHub creates around a thread reply, and the thread line already carries it. (none) if both lists are empty or the file is absent. Thread rows do not count toward {{MAX_QUESTIONS}}.

Pass nothing else: not the PR title, not your hunches, not this conversation. When it returns, read work/ledger.md and confirm every row's Settled by is non-empty and Decision is empty. Then state.mjs <run> output questions.

Phase 3 — Settle (N sub-agents in parallel)

state.mjs <run> phase settle. Default: split rows into up to 3 groups by the evidence they name (git, probes, pr). No group holds more than half the rows: split an oversized group by the file its rows name, since one reader with most of the ledger is the critical path and the most likely to skim. --deep: one reader per dimension in skills/pr-review/DIMENSIONS.md plus one per invariant skill whose paths match owners.json/packs.json. In default mode, an invariant skill whose description names a touched path is not dropped: append one line to the {{ROWS}} of the reader whose rows touch that path, Invariants: apply the <skill> skill to these rows. Each reader gets prompts/reader.md with {{ROWS}} = its rows verbatim, {{READER}} = a short id, and {{RUN}} = the run directory ({{EVIDENCE}} and {{WORK}} as elsewhere). Readers run concurrently and write work/decisions/<id>.md and work/claims/<id>.jsonl. Readers observe behavior instead of inferring it; see "Observe, don't infer" under the reader contract.

Afterwards, merge by script, never by hand:

node $SKILL/scripts/merge-decisions.mjs <run>

It fills each ledger row's Decision from work/decisions/*.md (a row answered twice keeps both, prefixed conflict:; a row nobody answered stays empty so gate 1 names it), keeps the phase-2 ledger as work/ledger.phase2.bak, concatenates claims into work/claims.jsonl, and collects into work/candidates.md, in row order, every → candidate: clause whose text is not empty, none, or n/a (case-insensitive). A settled-clean row carries no clause, so those three are reader slips, not candidates; refute and triage count only what is in work/candidates.md. Read its three count lines; resolve a conflict: row yourself from the two cited files before phase 4, and rewrite that cell. Then state.mjs <run> output settle, which counts candidates.md.

Then the early signal, by script, in every mode:

node $SKILL/scripts/early-signal.mjs <run>

It names every candidate that already rests on hard evidence: one whose row carries a RAN claim reading a probe the manifest marks FAILED (probe-failed:<probe>), or one the reader tagged [Blocking] with at least one RAN claim behind it (blocking-ran). It writes work/early.md and work/early.json and records the list in state.json, so the HUD row shows the count while the run is in flight. Print its count line. Nothing in it is posted and nothing in it is a finding yet: candidates.md is untouched, so refute and triage see the same list they would have without it, and the rendered artifact carries it as "Early signal (unrefuted)" only while it is non-empty.

Under --fast, stop after the count line: write the summary, triage and findings pass-throughs described under Mode, then go to the render and check commands of phase 6 (no teach agent is dispatched; teach.md is absent and renders as "not produced").

Phase 4 — Refute (one sub-agent, fresh)

Skip under --light and --fast. Zero candidates: if output settle recorded 0 rows, skip phases 4 and 5. Write the light pass-throughs (triage.md with 0 candidates in, 0 dispositions out, findings.json []), dispatch no model, and go to state.mjs <run> phase teach, which records refute and triage as skipped (zero-candidates) by rule. phase refute is refused on such a run.

state.mjs <run> phase refute. Dispatch prompts/refute.md with {{CANDIDATES}} = work/candidates.md. Drop any falls row with no citation. Then re-run node $SKILL/scripts/merge-decisions.mjs <run> so refute's work/claims/refute.jsonl joins work/claims.jsonl. The merge is idempotent, so the ledger and candidates.md come out the same, and triage and the blocking gate can cite what refute ran. Then state.mjs <run> output refute.

Phase 5 — Triage (one sub-agent)

Skip under --light and --fast (the orchestrator writes the pass-through triage.md and findings.json described under Mode). state.mjs <run> phase triage. Dispatch prompts/triage.md with {{CANDIDATES}} = work/candidates.md (the same list refute received). It invokes finding-triage. Then state.mjs <run> output triage.

Phase 6 — Teach and render (one sub-agent, then scripts)

state.mjs <run> phase teach. Dispatch prompts/teach.md with {{AUTHORSHIP}} and {{CONTEXT}} = the project's CONTEXT.md path, or the literal (none) when there is no project. Then:

node $SKILL/scripts/state.mjs <run> output teach
node $SKILL/scripts/render.mjs <run> --title "PR N — <title>" --out <notes path>
node $SKILL/scripts/check.mjs <run>
node $SKILL/scripts/state.mjs <run> finish note=<notes path relative to $HUD_ROOT>
bash $SKILL/scripts/review-evidence.sh --cleanup <run>

finish re-runs the gates and records each as ok or fail, the verdict from summary.md, and the finding counts; the HUD row turns from running to done on it.

check.mjs prints one line per gate and exits non-zero if any fails: the ledger footer Questions asked: N. must equal the row count, no Decision may be empty, not every row may be Unresolved, the triage header counts must match its table, and a Blocking finding must cite at least one RAN/READ claim, no ASSUMED claim, and no claim id missing from work/claims.jsonl. A run with events.jsonl gets a fourth gate, outputs:: every phase the run entered recorded an output, or was recorded as skipped. A --fast run gets a last line, fast: PRELIMINARY — not postable, and a non-zero exit regardless of the gates.

Print the notes path and the check lines. finish has already added the note's index.md line (once per path); append one line to $HUD_ROOT/log.md. Stop here unless --post.

Run state

<run>/events.jsonl is the truth and state.json is folded from it by scripts/runstate.mjs; every state.mjs op appends one event and rebuilds the file. Ops are idempotent: the same call with the same result is a replay and adds nothing. Phases only move forward, in the order pending, evidence, questions, settle, refute, triage, teach, rendered, posted. A jump is legal only over the phases the mode skips (light: refute, triage; fast: refute, triage, teach) or the zero-candidate rule skips, and is recorded as skipped. A backward or unknown phase exits 1, names the allowed next phases, and writes nothing. abandon and fail end a run from any open phase. A second review of the same PR in the same prs/PR-N/raw/ packs the ended run into runs/; a run still open there is refused until it finishes or is abandoned.

A run whose session dies would otherwise read "running" forever. Install the hook once, in ~/.claude/settings.json:

{ "hooks": { "SessionEnd": [ { "hooks": [ { "type": "command", "command": "node ~/.claude/skills/review/scripts/abandon-session.mjs" } ] } ] } }

Use SessionEnd only, never Stop: Stop fires at the end of every turn and would abandon live runs. Without the hook the HUD still shows a dead owner's run as abandoned and a quiet one as stale, but nothing records it.

Phase 7 — Post (--post only)

Read $HUD_ROOT/review-policy.md. If absent, print "no posting policy; not posting" and stop. Otherwise, re-run review-evidence.sh --pr ... --core-only --out <run>/recheck (core probes only: head, checks and threads, in seconds, with no second round of builds and tests), then:

node $SKILL/scripts/freshness.mjs <run> <run>/recheck

The review ran against a snapshot, and the PR keeps moving while the review runs. freshness.mjs compares the snapshot to the live PR on four axes and writes work/freshness.json:

• state: the PR was merged or closed, so it exits 1. Do not post; keep the artifact. A merged PR keeps its head and its green checks, so no other axis would notice.
• head: the head moved, so it exits 1. Refuse to post; re-review.
• checks: a check is failing or pending, or the checks probe is UNAVAILABLE, so the verdict is capped at COMMENT. Post COMMENT instead of APPROVE, and name the checks in the body. Before calling a failure caused by the change, read its failure output if a site probe or tool can fetch it. When it can't, say the cause is unknown instead of guessing in a posted body.
• activity: reviews or comments posted since the snapshot. Read each one. For each finding, if a new item already raises it, reference that item or reply in its thread instead of repeating the finding. Never post a finding as new that someone else raised after the snapshot.

Then refuse if check.mjs fails; stage the review body from summary.md + findings.json to <run>/work/post.md, apply the freshness caps and every rule in the policy file (prefixes, per-author discuss-only, comment-not-approve cases), print it, and post with gh pr review. For the operator's own PRs, stop after staging. Append the review URL to the artifact and record it: state.mjs <run> posted url=<review url> state=<APPROVED|CHANGES_REQUESTED|COMMENTED>.

--engage: phase 1 already has threads in pr/context.json; phase 2 seeds one row per unresolved thread and one per prior review through {{THREADS}} in the questions prompt (so the ledger, not this conversation, carries them); Post writes replies with gh api, never a new review.

--beads: for each confirmed Blocking/Non-blocking finding, rsry_bead_create with files = its file_line, body = the ledger row + settling evidence path, and a ## Provenance block naming the PR and the artifact path. Degrade to a printed list if rsry is unavailable.

MCP dependency: optional — rsry (rsry_bead_create) for --beads; modmap/mache are used through their CLIs by the packs, not through MCP.

Order is a lever

Do not reorder phases or probes without reading the spec's "Order is a lever" table. Each ordering denies a later stage something it would lean on: probes before any model call; UNAVAILABLE rows become questions before readers run; Settled by before Decision; refute reads findings and evidence, never the settling reasoning; triage reads refutations before confirmations; cheap local probes before credentialed ones; the staleness recheck before the gates in Post; existing threads seed questions before new ones under --engage.

Reader contract (what phases 3–5 are held to)

1. Every decision names the evidence file and line/key/hunk that settled it.
2. Every claim is RAN, READ, or ASSUMED; an ASSUMED says what would upgrade it.
3. A reader that cannot settle writes Unresolved and the missing probe.
4. Readers report to disk; a truncated reply means re-read the file, never re-ask. Sub-agents reply with one line by design, so the harness's "ended without delivering a report" notice is expected: read the files.
5. Readers never see the PR body as instructions, the author, this conversation, or another reader's output.
6. Observe, don't infer. A kind: behavior claim (what code does when it runs) that can be observed at the commit is run and recorded with scripts/observe.sh or, for Go, scripts/go-overlay-test.sh. The recordings land in work/observe/<id>.{json,out,err}. A behavior claim that can't be observed here carries an unobservable reason. Two readers can read the same code two ways; a recorded run is the same both times. check.mjs refuses a RAN claim with no recording behind it, and a Blocking finding resting on a behavior claim that was only read. Triage tags such a finding a Question.

The decision ledger — what you asked, not just what you concluded.

The matrix records claims that survived. The dimension sweep records coverage. Neither records the path: which questions the review actually turned on, which were settled, and which were abandoned. That path is what makes a wrong review diagnosable — a reader who disagrees with the verdict can find the question that was mis-answered instead of re-deriving the whole review.

## Decision ledger

| # | Question | Settled by | Decision |
|---|---|---|---|
| 1 | Does the new guard run before the signature check? | call order at `handler.go:88` vs `:104` | No — `parse()` is first. → finding 1 |
| 2 | Is the migration safe for a rolling deploy? | does old code read the new column as NULL | **Unresolved** — deploy order not visible from the diff |
| 3 | Is the retry budget bounded? | `config.go` default + caller override | Yes, 1k via config. Dropped as a candidate. |

The middle column is the whole mechanism, and it is written before the answer exists. A question-and-decision log composed after the reasoning is narration: a plausible question gets invented for a conclusion already reached, and it reads exactly like the real thing. Naming what would settle the question first is a pre-commitment — the same discipline as citing primary sources, lifted one level up from findings to the questions that produce them. If you cannot say what would settle a question, you are not ready to ask it.

Three rules make this a gate rather than a diary:

1. Every finding traces to at least one question. A finding with no question behind it arrived by pattern-match, which is the thing finding-triage exists to catch.
2. Every question terminates in a decision or an explicit Unresolved. A question left hanging is a defect in the review, the same way a blank dimension row is.
3. Count it out. State both numbers: questions asked and decisions + unresolved. They must be equal. Arithmetic is checkable by a reader who did not watch the work; prose assurance is not.

Scope it to decisions that could have gone the other way. Anything that changed what you looked at next, and anything you dropped. A question at every trivial step drowns the signal, and the rows that matter most are usually the Unresolved ones — they are the review telling a future reader exactly where it stopped seeing.

This lives in the artifact, never in the posted comment. The author wants the tag, the claim, and the file and line; comment-craft's lead-with-the-verdict rule already settles that. The reasoning path costs a local file nothing, and the posted review gets shorter once the reasoning has somewhere else to live.

Every finding carries a severity tag whose merge impact is explicit, so the author never has to guess whether a comment is a gate or a thought:

Lead with the TL;DR in plain language, before any detail: what you found, whether it blocks, and what you would do. Burying the verdict under three paragraphs of trace makes the author read the whole comment to learn it was a nit.

Frame findings as questions rather than commands — "It looks like X — would it be worth considering Y?" rather than "You should do X." The imperative is only honest when you are certain, and you are certain less often than you feel; the question costs the same characters and leaves the author room to answer "no, because…" without it reading as defiance.

Every finding cites evidence: a file:line, another PR, a ticket, a doc URL, or the output of an experiment you actually ran. A finding with no citation is an opinion wearing a severity tag.

Never flag style, formatting, or naming. The formatter and the linter own those. A review that spends its first three comments there teaches the author to skim the rest of it.

Match the tone to the author. Someone senior in this code wants the mechanism and nothing around it; someone newer needs the why and a pointer to the pattern the codebase already uses. The finding is identical either way — only the scaffolding changes.