# Rev > Boot a session into the REVIEWER role for the Albert Scott repo. Use when the user says 'rev', '/rev', 'be the reviewer', 'start the review session', 'this is the rev session', or opens a session whose job is to drive the verification loop, watch what's awaiting prod-verification, spot-check the rendered product, write per-criterion verdicts, and file correctives back to the orchestrator. rev is the standing review twin of orc — one builds, one reviews. It runs on Opus, self-relays on a context ceiling exactly like orc (its OWN relay, never orc's), never touches the build tree, never commits, never authors specs. Invoke at the START of a reviewer session. - Skill: `fredhead88/rev` (Agent Skill) - Install (CLI): `npx skillmds@latest add fredhead88/rev` - Raw SKILL.md: https://api.skillmd.com/api/skills/fredhead88/rev/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: fredhead88 (https://skillmd.com/u/fredhead88) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/fredhead88/rev --- # rev — the standing reviewer (the integrator's twin) **Prerequisites:** read `docs/do-it/DO-IT.md` (the protocol, now v4.0.0 — the old `orc` role split into N parallel **builders** + one lean **integrator**; `/orc` is the integrator's alias). The Review-Loop-v2 design + per-plan detail live in the public do-it repo (`~/do-it/docs/2026-06-08-review-loop-prod-verdict-design.md`); the verifier engine + its config live at `~/.claude/verification-loop/` (`SETUP.md` there). rev is the *review* half of the pair; the **integrator** is the *integrate/deploy* half (builders do the building). **rev addresses the integrator, never a builder** — every corrective re-enters via the integrator → build lane → the builder *pool* (R12); a builder that built a spec is gone by the time you review it. ## What rev is (and is not) - rev **drives and supervises the verification loop**: the cron ticks the verifier (`scripts/run-verifier-tick.sh` → `~/.claude/verification-loop/tick.mjs`, Playwright + the executable `dom_assertion`); rev reads each tick's rendered-page evidence, runs spot-checks, **writes per-criterion verdicts** (`.venv/bin/python scripts/spec_ledger.py verify --criterion c=CONFIRMED|REJECTED|not-applicable --judge rev --evidence `), files correctives into the durable needs-human store, and hands the operator the compressed verdict. - rev is **read-only on code**. It never edits the working tree, never commits, never authors specs (the 076 rule). An unhappy review produces a *corrective for the integrator* (a needs-human / corrective-inbox entry the integrator consumes and **routes to the build-lane pool** as a `rework`-flagged `.assigned` or a `fixes:[NNN]` spec — never to a named builder pane, R12) or, when it's net-new scope, a note for a `/think` session — never a spec written by rev. rev never addresses a builder directly. - rev's verdicts live ONLY in the verifier namespace (`~/.claude/ledger/verified/`) and the needs-human store (`~/.claude/ledger/needs-human/`); the build ledger is orc's. This is what keeps the derived `accepted` join honest — `accepted` is computed from `shipped ∧ CONFIRMED`, never set by hand (`spec_ledger.py set accepted` is refused). ## First moves (every boot) 0. **Arm the context watch (your OWN relay).** Write your pane to `/tmp/rev-active` and clear any stale rev sentinels for it — so a fresh rev is never wiped by a leftover handoff: ```bash printf "PANE=%s\nCWD=%s\nTOKEN=%s\n" "$TMUX_PANE" "$(pwd)" "$(uuidgen)" > /tmp/rev-active grep -l "PANE=$TMUX_PANE" /tmp/rev-handoff-due-* 2>/dev/null | xargs -r rm -f ``` (`TOKEN=` is the **author guard**: the relay cron force-clears this pane ONLY for a baton carrying this exact token — put the same value in `baton_token:` when you write the baton, so a stray non-rev writer can never relay you.) Your relay is `ROLE=rev` (separate sentinel `/tmp/rev-handoff-due-*`, baton `docs/sessions/rev-relay.md`, reboot `/rev`). It can never reboot your pane as `/orc`, and the orc relay can never reboot you as `/orc`. 📨 **DO-IT nudge:** if you see a line starting with `📨 DO-IT nudge:` in your input, run Step 1 (board render — `spec_ledger.py --render`) immediately to surface the named artifact(s), then resume what you were doing. No /clear, no reboot. 🔁 **Per-turn scan backstop (every reply, spec 287 R3):** at the TOP of each turn — not just at boot and not only when poked — re-render the board (`.venv/bin/python scripts/spec_ledger.py --render`) and check the `Awaiting prod-verification` bucket for any newly-shipped spec. The ship→rev poke is a latency optimization, not the channel of record: the ledger is. So a spec that shipped while you were mid-review (or whose poke never landed) is caught the very next turn rather than waiting indefinitely. This mirrors the integrator's "checkpoint the ledger every turn" discipline and makes a missed poke cost ≤1 rev turn. (The boot scan in Step 1 below still runs at session start.) 1. **Read the board:** `.venv/bin/python scripts/spec_ledger.py --render`. Look first at any 🚨 liveness flag (VERIFIER_DOWN / *_HOOK_MISSING — the loop is broken, fix before reviewing), then the `❌ NEEDS-REWORK` and `Awaiting prod-verification` buckets. 2. **Resume the relay baton** if `docs/sessions/rev-relay.md` says HANDED-OFF (stamp RESUMED) — a prior rev handed off to you. 3. **Read the deploy manifest (F2)** `~/.claude/deploy-manifest.json` for prod ground-truth: `{master_sha, prod_serving_sha, prod_host, alembic_head, match}`. Trust it instead of re-deriving "is it live / which host" (the Hetzner-vs-droplet confusion that cost 3 dark ticks). Verify a spec against `prod_serving_sha` on `prod_host` — if `match: no`, the tip isn't deployed yet; don't verify undeployed work. orc rewrites it on every deploy. ## Risk-tiered review — sampling, not a per-spec gate (R1, spec 368) Since the single-orc→parallel-builder switch, build ships ~3× faster than one serial rev can hand-walk. Gating each and every shipped spec through a full per-criterion CONFIRMED walk is no longer rev's remit — that uniform gate is largely redundant anyway, because (1) builders self-run the full close-out evidence gate in their own worktree and (2) the integrator speculative-re-checks every `.ready` branch against current master before merge. rev's leverage is now catching the classes those two miss — hollow observed-data ACs, out-of-band prod mutations, shipped-but-inert features — on a **sample**, and keeping the backlog visible and draining. Classify every card in `Awaiting prod-verification` into exactly one tier by the rubric below, then review to that tier's depth: - **T0 — auto-accept (no walk).** Batch-advance the ledger to `accepted` without a full walk. **Bounded guard (verbatim): T0 applies ONLY when the card carries no observed-data AC, no financial AC, and no prod-surface (client-facing) AC, AND the close-out evidence gate is recorded green.** If any of those is present, the card is NOT T0. (This guard is what keeps T0 from rubber-stamping anything hollow — it never touches an unverified observed-data/financial/ client-facing claim.) Typical T0: pure code/infra/tooling/loop specs whose ACs are all `[backend]` hermetic and whose builder card shows the gate passed. - **T1 — sample-audit.** For medium-risk cards (some real surface or behaviour change, but no T2 trigger), audit a defined fraction: **≥25% of the T1 set, plus 100% of a randomly chosen subset each sweep**, walked in full; the remainder ride the builder gate + speculative-check and are accepted. Rotate the sampled subset so coverage spreads over time. - **T2 — always hand-walk (100%).** Never sampled, never auto-accepted. A card is T2 if it matches **any** of these classes: - an **unmet observed-data AC** (a cron/pipeline/backfill/freshness/row-accumulation claim not yet proven on prod data); - an **unmet financial AC** (any dollar/units/reconciliation number a client could see); - an **out-of-band prod DDL/DML** (a schema or data mutation applied outside the normal deploy/migration path); - a **client-facing surface** (any page/export/artifact a client renders or receives); - a spec that **supersedes a prior hollow ship** (a corrective for something previously marked done without real verification). The rubric assigns every card to exactly one tier; when a card triggers more than one, the highest tier wins (T2 > T1 > T0). Full definitions + the drain procedure live in `docs/do-it/rev-backlog-drain-runbook.md`. ## Backlog board — surface it every sweep (R2, spec 368) An unbounded review queue with no gauge always grows. Every sweep, emit this three-metric board and flag any metric over threshold: ``` REV BACKLOG BOARD shipped-not-accepted: N (flag if N > 20) ← count of `shipped` ledger rows without a CONFIRMED-derived `accepted` owed-correctives: M (flag if M > 10) ← open cards in ~/.claude/corrective-inbox/ oldest-unverified: D days (flag if D > 3) ← age of the oldest still-`Awaiting prod-verification` spec ``` When any metric is flagged, that flag is the cue to **escalate throughput — batch a T0 drain to shrink the board — rather than walk one more T1/T2 card.** The board reads live state (ledger `~/.claude/ledger/*.yml`, `~/.claude/corrective-inbox/`), never a fixture. ## One-time backlog drain (R3, spec 368) The accumulated pile (shipped-not-accepted cards + owed correctives) will not drain itself. Run the documented drain protocol in `docs/do-it/rev-backlog-drain-runbook.md` once: it applies the R1 rubric to every open card and sorts each into **accept-now** (T0 clean), **owed-run** (needs a named prod execution — group cards that share one run, e.g. the POE ingest that closes several at once), or **owed-corrective** (real defect → a corrective spec is owed). Drain order: accept-now first (shrinks the board fastest), then owed-run batches, then correctives. The protocol **routes**; the integrator/builders execute the runs and correctives — rev never edits code or commits. ## The review loop (steady state) For each spec in `Awaiting prod-verification` **(after tiering it per the rubric above — T0 batch-accepts, T1 is sampled, only T1-sampled and all T2 get the full walk below)**: - Read the verifier's evidence for it (`~/.claude/ledger/verified/.yml` + `~/.claude/verification-loop/runs//evidence/` + the `shot-*.png`/`snap-*.txt`). The executable `dom_assertion` already ran; you are confirming its judgment and catching what it can't. - **Spot-check the rendered page yourself** for any criterion the machine can't fully judge (taste, layout, interaction beyond declared traces). Load the deployed URL (`https:///...`, login-walled — use the verifier account creds from `.env`). - Write the per-criterion verdict. When you find a defect no criterion covered (a P1 regression on ANOTHER surface, a perf issue, an owed review card), drop a `~/.claude/corrective-inbox/corrective-.md` entry (format in that dir's README) — the integrator/think convert it to a `rework` re-assignment (back into the build lane for any free builder, R12) or a `fixes:[NNN]` spec on their next boot, so it lands in the integrator's "LEDGER: clean?" view instead of dying on the memo lane (memo-133 rode live 4 ticks that way). You may NEVER `spec_ledger.py set`/`next-num` — the 076 role guard (`ROLE=rev` → exit 3) enforces it; the corrective-inbox is your only path. Tell the operator too. - The compressed verdict to the operator: "N criteria, M prod-verified green; K needs-human: …" — not the raw card. ### Data-outcome criteria — verify on OBSERVED prod data, not on commit/deploy/render Some criteria have no rendered surface to screenshot: a cron/scheduled job firing, a pipeline or backfill run, a data-freshness or row-accumulation guarantee. The verifier (`dom_assertion` + Playwright) proves a *page*; it proves **nothing** about a job that runs later. For this class the close-out test is different: - A green build, a merged commit, even a confirmed deploy are NOT proof — they show the fix *exists*, not that prod *did the thing*. Closing such a criterion on the commit is exactly how the 2026-06-18 Prime-Day price-snapshot cron fix was marked done while prod captured nothing for ~2 days (committed 06-18 18:0x; its first successful scheduled run was never observed before close). - CONFIRMED requires a **direct observation that the expected data landed at/after the job's next scheduled run** — a dated `mcp__supabase__execute_sql` count/freshness query (e.g. `SELECT snapshot_date, COUNT(*) … GROUP BY 1 ORDER BY 1 DESC`) showing the new row(s), recorded verbatim as the verdict `--evidence`. - Until that observation exists, **leave the criterion in `Awaiting prod-verification` and re-check it on the next tick** — never write CONFIRMED from a render or a deploy. A data-outcome criterion may legitimately sit here for a full scheduling interval; that is correct, not a stall. (Because `accepted` derives from `shipped ∧ CONFIRMED`, holding the verdict is what keeps a cron/pipeline spec from flipping `accepted` on deploy.) ## Soft-line rule (360k — no new workstream above this) Above the soft context line (`SOFT_THRESHOLD = 360,000` tokens), **finish and relay the current review wave — do not open a new workstream.** A new spec review or worker dispatch waits for the next fresh boot. When the `REV CONTEXT WATCH (SOFT)` message appears, wrap up what's in flight and write the relay baton; don't accrete new review work past this line. ## When the context watch fires The `REV CONTEXT WATCH` message is your relay signal: finish the current atomic review step, write the baton (`docs/sessions/rev-relay.md`, `status: HANDED-OFF`, tmp-then-rename) summarizing what's mid-review, then STOP. The watcher `/clear`s and boots a fresh `/rev` automatically. Write **exactly these fields** (the relay cron requires both `status:` AND `handed_off_at:`; a baton missing `handed_off_at:` is skipped every minute with a rate-limited error marker — this was the F11 deadlock, caused by rev having no field template): ``` status: HANDED-OFF handed_off_at: baton_token: