/super-review

name: super-review
description: Reviewer lane of the super-board pipeline and standalone PR/branch readiness review — forms its own hypotheses before reading the builder's summary, remembers prior findings and re-checks each with file:line proof, runs an adversarial truth-check on non-trivial diffs, and classes every finding (Gap, Bug, Verification miss, Scope drift, Over-engineering via `ponytail:ponytail-review`). Merges only through `super-board-merge-gate.sh`, pinned to the reviewed head SHA, and routes other fixes to Super Build or Super QA via the board. Use when the user says "Super Review", "review this branch", "review loop", "make sure this is merge-ready", "PR review", or asks for code, architecture, security, QA evidence, or release-readiness judgment.

**For a board worker, before writes or worktree creation:** follow [skill readiness](../super-board/references/skills-readiness.md). Resolve this lane for the actual host, load the report's files/fallbacks, halt on missing requirements and recheck each conditional helper before use.

Super Review — PR/code readiness reviewer

**Super Review** is the super-board reviewer. It checks whether a branch or PR is safe to merge, records actionable findings, and routes fixes to the right Super workflow.

Super Review should be conservative with claims: only say **merge-ready** when review evidence is clean and verification has passed. If evidence is missing, say what is unverified.

When to use

Use this skill for:

• PR or branch review before merge.
• Code, architecture, security, data-model, or migration judgment.
• Release-readiness checks after Super Build, Super QA, or a human's `/ui-refine-loop` pass.
• The Review lane of a `super-board run`.
• A final pass that needs risks, blockers, and human gates summarized.

Do **not** use this as the primary implementation workflow. Route fixes to:

• **Super Build** for feature/task implementation from GitHub Project `Ready` issues.
• **Super QA** for functional bugs, broken behavior, failing Playwright paths, or missing QA coverage.
• Visual fidelity, layout, screenshots, wireframes, or design-system drift: file a UI ticket; a human can run `/ui-refine-loop`. The board never triggers it.

Inputs

Accept any of these inputs:

• current branch or local diff;
• GitHub PR number or URL;
• commit range;
• user-provided file list;
• QA report, screenshots, or super-board wave report;
• release goal / done definition;
• `prior_report` — the previous review's findings on this PR (see "Review remembers"). Empty on a first review.

If the input is ambiguous, default to reviewing the current branch against its upstream/base branch. Ask only when the base branch, PR, or target scope materially changes the result.

Review flow

1. **Establish scope**

• Identify branch, base branch, PR, changed files, and user goal.
• Check working tree status before reviewing.
• If there are unrelated dirty files, stop and ask before touching them.
• Load `prior_report`. If one exists, run round 1 of "Review remembers" before step 2.

2. **Inspect changes — your own pass first**

• **Before reading the builder's account** (PR description summary, `[builder] [report]` comment, Tester

handoff), read the issue's acceptance criteria and the raw diff, and write down 2–4 hypotheses: what must be true for this to be right, and where it would most likely break. Reading their summary first anchors you on their framing; the point of a reviewer is a second, independent solver.

• Then read their claims and check each one against the code and test output, the same

way you check your own hypotheses. A claim is a lead, not evidence.

• Read the diff and the affected modules.
• Load `mattpocock-skills:codebase-design` and read the diff through its vocabulary

— **module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**. Ask the shape question the diff raises: does this land behind a small interface, or does it widen one? Apply the deletion test to anything the diff adds that looks shallow.

• Scope is the diff, **never the whole codebase**. A hot spot three modules away

is not this PR's problem.

• Check app-specific conventions from the nearest `CLAUDE.md` / `AGENTS.md`, especially:
• `clock.now()` instead of `new Date()`;
• services own business logic, repositories own data access;
• job handlers own outer transactions;
• money uses `numeric(12,2)`;
• calendar days use `date`, not `timestamptz`;
• structured `AppError({ error_code, context })`;
• jsonb writes are Zod-validated.

3. **Classify findings** — every finding gets a **class** (what kind of problem) and a **severity** (does it block). Class:

• **Gap** — an acceptance criterion or requested behaviour is missing or incomplete.
• **Bug** — the code likely fails or regresses behaviour.
• **Verification miss** — the code may be right, but the evidence does not prove it

(missing test, test asserts the wrong thing, skipped rerun).

• **Scope drift** — the diff changes something the issue did not ask for, or skips a

stated constraint.

• **Over-engineering** — the diff works but builds more than the AC needs: a new

dependency, abstraction, config or file where the codebase, stdlib, a native feature or one line already covered it. Find these with `ponytail:ponytail-review` on the merge-base diff (`git merge-base HEAD origin/<base>`); plugin not installed → ask the ponytail ladder of each addition yourself: needed at all? already in the codebase? stdlib? native? an installed dep? one line? Always **Should fix**, routed to Super Build — it **never blocks a merge on its own**. A simplification that would cut validation, security, data-loss protection or accessibility is not a finding.

• **No issue** — you checked a hypothesis or claim and it holds. Not a finding: l