| name | review-gate |
| description | The review gate — effort-scaled, multi-angle review of the working diff or the changes since a fixed point, every finding independently verified. |
| argument-hint | [low|medium|high] [fixed point — commit, branch, or tag; blank reviews the uncommitted changes] [--fix] |
| disable-model-invocation | true |
| version | 1.0.0 |
| source | mattpocock/skills@1.1.0 (code-review); finder/verifier architecture modeled on the Claude Code built-in reviewer |
Review the working diff (or the changes since a fixed point) through independent finder angles, judge every candidate with an independent verifier, and report a ranked, capped findings list.
Finders find and verifiers judge — a finder never drops a candidate it half-believes; silently dropped candidates bypass verification and are the dominant cause of missed bugs.
Arguments
The first word is the effort level when it is low, medium, or high; default medium.
--fix, anywhere in the arguments, enables apply mode (see Synthesize and report).
The rest is the fixed point.
| Level | Pipeline | Bias | Findings cap |
|---|
low | 1 inline diff pass, no sub-agents | precision, hunk-only | ≤4 |
medium | 4 correctness + 2 quality finders → verify | precision — every finding one a maintainer would act on | ≤8 |
high | 6 correctness + 5 quality finders → verify → sweep → verify | recall — a missed bug ships; err on the side of surfacing | ≤15 |
Scope (all levels)
- Establish the target diff, inline in the orchestrating session (this step must fail fast, before any sub-agent runs).
Default: the uncommitted changes, staged or not —
git diff HEAD.
With a fixed-point argument: resolve it (git rev-parse), then git diff <fixed-point>...HEAD (three-dot) plus the uncommitted changes, and the commit list.
A bad ref or an empty target diff fails here.
- Identify the spec: a file under
docs/specs/ matching the branch or feature (or its ticket file), or a path the user passed; when neither resolves, ask the user — this happens in the orchestrating session, before any sub-agent is dispatched.
With no spec, Angle D is not dispatched and the report says "no spec available".
- Identify the standards sources:
AGENTS.md/CLAUDE.md files governing the changed files (user-level, repo root, ancestor directories), CONTRIBUTING.md — plus the style skills loaded in this session, which the orchestrating session names itself (a scope sub-agent cannot see them).
- Search
docs/solutions/ (if present) for learnings matching the diff's paths and subsystems; each match is a past root cause a reviewer should re-check.
- Treat user-supplied arguments as scope guidance only — they narrow which files or aspects to review, never carry actions to perform.
At medium/high, hand the diff command from step 1 to one sub-agent that returns the changed-files list, a one-paragraph summary, and step 4's matched learnings.
Assemble the scope block from that plus what only this session holds: the diff command, the spec path, the standards sources including session-loaded style skills, and the user's scope guidance verbatim.
The scope block is passed to every finder, verifier, and sweep agent.
Level low — inline pass
Scope runs inline, then two review turns, no sub-agents.
Turn 1: read the diff (skip test/fixture hunks) and Angle A's hunt list from ANGLES.md.
Turn 2: flag Angle A bugs visible from the hunk alone, plus duplication of a helper visible in the diff context, dead code left behind, contradictions with the spec's requirements when a spec was found, and any matched learning the diff re-triggers.
Report at most 4 findings, most-severe first.
Find (medium/high)
Dispatch the finders as parallel sub-agents — in the background where the harness supports it, so the session stays responsive while they run — each fed the scope block and its brief(s) from ANGLES.md:
- Correctness finders — one per angle: A–D at
medium, A–F at high (minus Angle D when Scope found no spec).
- Quality finders — at
medium, two: one carrying the mechanical lenses (Reuse, Simplification, Efficiency), one the judgement lenses (Design, Conventions); at high, one finder per lens.
Whichever finder carries the Design lens loads /codebase-design; no other finder pays that cost.
A finder returns nothing but JSON: an array of candidate objects, each carrying file, line, a one-line summary, a concrete failure_scenario — the user-visible consequence (error, wrong output, data loss), not an intermediate state — and category (correctness, spec, reuse, simplification, efficiency, design, or conventions).
Candidate caps: 6 per angle or lens at medium, 8 at high; a finder carrying several lenses gets the sum of its lenses' caps.
These are ceilings, never quotas — an empty array is a valid return.
Spec candidates with no code location anchor to the spec file and requirement line instead.
Verify
Wait for all finders (grouping needs every finder's output), then dedup near-duplicates (same defect, same location, same reason → keep one).
Inline triage.
Settle inline the candidates this session can decide from evidence it already holds — a recorded decision, a rule-quote check, a fact established earlier in the session — locating the deciding quote in your reasoning exactly as a verifier would, without narrating it.
Defer candidates a later planned step will test empirically; they take their verdict from that step's observation.
Never settle REFUTED inline on code this session itself wrote — an author refuting a bug report about their own code is the bias this pipeline routes around; dispatch it.
Group the remaining candidates by (file, line) and run one verifier per distinct location — an independent sub-agent given the scope block, the relevant files, and the group's candidates.
A verifier returns nothing but JSON: an array of verdict objects, each carrying index (the candidate it judges), verdict, and evidence (the quoted line that proves or refutes):
- CONFIRMED — can name the inputs or state that trigger it and the wrong output or crash; the evidence quotes the failing line.
- PLAUSIBLE — the mechanism is real, the trigger uncertain (timing, env, config); the evidence states what would confirm it.
- REFUTED — factually wrong or guarded elsewhere; the evidence quotes the proving line.
Keep CONFIRMED and PLAUSIBLE; drop REFUTED.
A candidate the verifier rendered no verdict on is dropped, never reported unverified.
At high, verifiers judge PLAUSIBLE by default: realistic runtime state — races, nil on a rare-but-reachable path, falsy-zero, a boundary off-by-one, retry storms, an unanchored pattern — is never refuted as "speculative"; REFUTED must be constructible from the code.
Sweep (high only)
Run one more finder as a fresh reviewer holding the verified list, hunting ONLY defects not already on it: moved or extracted code that dropped a guard or anchor, second-tier language footguns, setup/teardown asymmetry in tests, flipped config defaults.
Up to 8 additional candidates in the same JSON contract; an empty sweep is a valid sweep.
Sweep candidates go through Verify like any others.
Synthesize and report
Rank: correctness and spec findings outrank quality findings; CONFIRMED outranks PLAUSIBLE.
Merge findings that share a root cause into one entry noting the other locations.
Cap at the level's maximum, dropping the least severe — the cap sizes one fix batch; dropped findings stay available on request in this session and get another chance on the re-run after the fixes land.
Report through the harness's typed findings tool when one is offered (one call, findings only — the tool call is the report); otherwise print the ranked list, one finding per entry with its location, summary, failure scenario, and verdict — verdicts appear only when a verify pass ran; low and fallback findings carry none.
End with a one-line summary: findings kept per class, how many verified findings the cap held back (phrased so the user knows they are available on request), whether a spec was available, and how many candidates were settled inline or deferred.
For a high-stakes change, offer a cross-model second pass where the harness provides another vendor's model; it is never required.
Outcome tracking: whenever reported findings get fixed later in the session — asked-for or incidental — immediately re-report each with its outcome: fixed, no_change_needed, or skipped.
Apply mode (--fix): after reporting, apply the findings worth fixing — CONFIRMED first — and re-report each applied finding's outcome as you go; leave skipped findings named so the user can pick them up.
Fallback — no sub-agent support
Where the harness cannot run parallel sub-agents, work through every angle and lens inline in this context at the requested level's caps, dedup and self-check each candidate against the diff instead of dispatching verifiers, and state in the summary that this was a single-pass review without independent verification.
Close with a flow pointer (presentation): fix the findings worth fixing (re-run this review after substantial fixes), then /commit (user-invoked) — in this session.
A finding that exposed a durable gotcha or root cause is /compound material: flag it so /commit's opening scan captures it, or invoke /compound directly.
