Quality Gate

Repository context. Gather first

Collect these with individual Bash calls, one command per call, never combined into a single invocation:

• Current branch, git branch --show-current
• Working tree status (empty = clean), git status --porcelain | head -20

The pipe is the bound and belongs in the command. A read-time cap ("read only the first 20 entries") bounds nothing: the Bash tool returns the command's complete output into context before there is anything to decide about.

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as separate body Bash calls rather than pre-compute lines: the harness runs a skill's whole pre-compute block as one shell invocation, and a worktree-isolated session refuses a compound command that contains git. The dated record for that composition claim is the worktree skill's reference/gather-block.md, "The pre-compute block runs as one shell invocation".

Pre-computed context

Open PRs (match headRefName to current branch above; baseRefName is the PR's real base): !gh pr list --json number,title,headRefName,baseRefName --limit 10 2>/dev/null || echo "unknown"

Purpose

Review is the quality checkpoint between "code works" and "code is ready." This skill structures that step so changes are inspected for consistency, correctness, and alignment with the project's conventions before verification or PR creation. Self-review catches errors tests miss. Inconsistencies, loose ends, convention drift, design shortcuts. Delegated reviews (code, architecture, security) bring specialized scrutiny the implementer's tunnel vision would miss.

Depth, not breadth. This skill picks ONE lens per invocation. For a multi-surface fan-out that runs many reviewers at once and ranks their combined findings, use this plugin's fanout skill instead.

Shared inputs

• Review diff base. mode-scoped override first: close-out does not use this base at all. A spec container is not a branch, so that mode derives a container-scoped basis of its own, per execution shape (context/close-out.md "Why it needs its own diff basis"). Every other mode uses the base below. When an open PR exists for the branch, its baseRefName is the base: dispatched reviewers diff git merge-base origin/<baseRefName> HEAD. The pre-computed PR list above is capped; when the current branch is absent from it, run gh pr list --head <current-branch> --json number,baseRefName before concluding no PR exists. Otherwise git merge-base origin/HEAD HEAD (falling back to the remote's resolved default branch via git ls-remote --symref, then origin/main, then HEAD) so committed-clean branches still show their changes; untracked files come from git ls-files --others --exclude-standard.
• Severity vocabulary, the project's own review docs when present; else ${CLAUDE_PLUGIN_ROOT}/context/severity.md.
• Criteria resolution. Review criteria resolve through the standards index per the plugin binding ${CLAUDE_PLUGIN_ROOT}/reference/standards-contract.md (its "Resolution ladder" section owns the procedure), detailed in context/criteria.md.
• Findings location. Resolve through the plugin binding, ${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md, which owns the resolution ladder, its non-interactive collapse, the <branch-slug> and <UTC-timestamp> spec, and the self-ignore guard. Resolve the home; never assume its shape, the ladder's rungs do not all compose a reviews/<branch-slug> segment. Durable findings are <UTC-timestamp>-<mode>.md in the resolved directory. Write repo-relative paths only, never absolute machine paths.

Step 0: Detect review mode

$ARGUMENTS, optional mode selector. When given, use it directly; otherwise infer:

Ambiguous → present the modes and ask. Read the matching context file before proceeding.

Step 0.5: Pre-flight gate (diff-consuming modes only)

Mode-scoped by design. criteria is a reference mode. It loads criteria rather than reviewing a change, and legitimately runs against a clean tree, so it is exempt and never gated. close-out is gated, but on its own basis, not this one: it runs the same two checks below against the container-scoped basis it derives, plus a rollup check that the container is actually finished (context/close-out.md "Step 4"). Every remaining mode consumes the branch review diff, so for those: resolve the review diff base ("Shared inputs") and confirm it yields a non-empty diff BEFORE dispatching any reviewer.

• Unresolvable base, an open PR's origin/<baseRefName> fails git rev-parse --verify even after a fetch (do NOT silently substitute a different base. That reviews the wrong diff), or no ladder ref resolves at all → report which ref failed and STOP.
• Nothing to review. No tracked diff against the base AND no untracked files → say so and STOP; never stage files to manufacture a diff.

Untracked-only is reviewable here, and this is a deliberate divergence from fanout. This skill's Shared inputs hand untracked files to the dispatched reviewer directly ("Shared inputs"; the self and slice worker templates both read them), so a branch whose whole change is new files has a real change set. Stopping on it would make a new-module or new-test review report "nothing to review" about work that is plainly there. fanout stops on that case because its surfaces receive only the merge-base diff, which cannot show an unstaged file. Review the untracked files in place; still never git add them.

Either outcome dispatches ZERO reviewers: a lens run against an empty or wrong change set produces noise, not a verdict. Two modes add a gate of their own on top of this one: an explicitly passed --spec ref that does not resolve is a STOP (context/spec.md "Rung 1"), and so is an explicitly passed --container ref that does not resolve (context/close-out.md "Step 1").

Step 1: Gather context

1. What changed?. Pre-computed facts above + the review diff base
2. What was the goal?, the original task, approved plan, or user intent from conversation. In every mode but spec and close-out this is background for judging the change; making the goal the thing under judgment is spec mode, which owns the spec-source discovery ladder and the fidelity finding classes. close-out is that same lens at container scale, reusing both and resolving its spec from the container instead of the branch
3. What conventions apply?. Resolve the project's standards for the changed surfaces through the standards index per the Shared-inputs criteria-resolution binding, so every review mode grounds in the same rows plan formulation loaded

Step 2: Execute the review

Follow the selected context file. Two hard rules:

• Self mode never runs the checklist on the producing thread. Dispatch a fresh-context read-only subagent; the thread that wrote the code rubber-stamps its own recap.
• Delegated modes synthesize, never substitute. After the delegated reviewer returns, verify each finding against the actual diff (a subagent's report is synthesis, not evidence) before presenting.

Step 3: Report findings

## Review: [mode] — [branch or task name]

### Findings

| # | Severity | Confidence | Category | Finding | File:Line | Action |
|---|----------|------------|----------|---------|-----------|--------|

### Strengths

- What is done well — review should validate, not only criticize

### Verdict

- [ ] Ready to proceed — no blocking findings
- [ ] Needs fixes — N findings require attention

Step 4: Handoff

• All clear. Suggest the project's next verification step (build/test, outcome verification, PR creation)
• Fixes needed. List specific actions; after fixes, suggest a quick re-run of self mode
• Design fundamentally flawed. Suggest revisiting the plan/design before more code lands

What this skill does NOT do

• Does not run builds or tests. Use the project's build/test tooling (or this plugin's ecosystem-specialist agent) separately
• Does not write or fix code. It identifies issues; the implementer fixes them
• Does not fan out across many surfaces. That is this plugin's fanout skill

Gotchas

• Don't skip self-review for "small" changes. Small changes have the highest ratio of "obviously fine" to "actually had a bug."
• criteria mode is a reference, not an action. It loads review criteria so you can see what to check; combine with self mode for an informed review.