---
name: review
description: >-
  Standalone, on-demand review entrypoint over the shared draft+pre-approval
  fan-out/fan-in gate procedure. Runs ONE `review`-gate round on any PR — draft
  or ready, with no dev-loop lifecycle obligation — and posts the single-surface
  verdict. Never fixes, never flips ready-for-review, never moves a board item,
  and never satisfies draft_gate/pre_approval_gate evidence.
allowed-tools: read bash
user-invocable: false
---

# Review

`review` is an informational gate on any PR (draft or ready). It never blocks a
lifecycle transition, waits on CI, auto-resolves, or satisfies lifecycle evidence.

**Ownership-exempt (issue #1850).** It makes no branch push, fix commit, merge,
board move, or assignee claim. Enter either from the interactive review-intent
shortcut or deterministically via `loop startup --pr <n> --review`; neither path
consults the single-contributor ownership gate. Read the
[ownership boundary](../docs/public-dev-loop-contract.md#single-contributor-ownership-gate-resolve-dev-loop-startup)
when distinguishing this route from write-capable follow-up, which stays gated.

## Interface

```
/loop-review <pr>          # interactive: ends with a submit choice
/loop-review <pr> --auto   # headless: posts a COMMENT review, no prompt
```

`<pr>` is a pull request number or URL, required. `<owner/repo>` resolves from
the git remote at invocation, same as the other loop commands. `--auto`
mirrors `/loop-grill`'s (`/dev-loops:loop-grill` in a consumer install)
headless flag (`skills/loop-grill/SKILL.md`).

In a consumer (plugin) install this runs as `/dev-loops:loop-review <pr>`; the
bare `/loop-review` form is dev-loops-repo-local (repo-local
`.claude/commands`).

## What it runs

Read [Gate-review sub-loop contract](../docs/gate-review-sub-loop-contract.md) before execution. Reuse its context, fan-out and fan-in procedure with `--gate review` through every stage; run the judge phase (Phase 3.5) between fan-in and the verdict post, and stop after verdict-post and the submit choice, before fix or repeat phases.

When the `review` route runs inside a `dev-loop` agent (`loop startup --pr <n> --review`), that
agent dispatches one `gate-coordinator` agent for the round. The `gate-coordinator` agent runs
steps 1 to 3 and step 4 up to the ledger write, dispatches the `review` agents, and returns the
typed round result without the act-list path, the spec-authority identity path and the judge
summary, since the coordinator runs no judge phase (`GATE-EXEC-GATE-COORDINATOR`). The `dev-loop` agent
then runs Phase 3.5 below, rewrites the durable ledger with the judge flags, and runs the
`upsert-checkpoint-verdict.mjs` post and the submit choice. In the main session
this skill dispatches the `review` agents directly.

1. **Phase 1 — context-builder.** `node scripts/github/write-gate-context.mjs
   --repo <owner/repo> --pr <n> --gate review --head-sha <sha> --base <ref>
   [...]` — the SAME build-once neutral bundle (diff + adjacent code) draft/
   pre-approval get. Angle resolution for `review` is NOT dynamic/tiered: it is
   the deterministic UNION of `draft`'s and `preApproval`'s configured angle
   sets (`resolveReviewGateAngles` in `write-gate-context.mjs`). The
   spec-of-record-dependent angles — `acceptance-criteria`, `pr-checklist`,
   and `pr-description` — are each DROPPED (with a recorded
   rationale entry, reason `"no spec-of-record"`) only when the PR closes no
   issue AND its own body carries no AC checklist; all are KEPT when either
   is true. `pr-checklist` is also DROPPED (reason `"no formal spec on the closing
   issue or PR description"`) when neither the single closing issue nor the PR
   description passes `requireSpecFromBody`; an unknown fact keeps every angle.
   The review gate always DROPS `gate-evidence` (reason `"the standalone review
   has no lifecycle gates"`), with or without a spec of record.
2. **First-wave release.** Same `GATE-EXEC-FIRST-WAVE-RELEASE` contract as any
   other gate fan-out: no primer and no lead reviewer; release the first wave
   immediately after emission.
3. **Phase 2 — fan-out.** One independent, fresh-context `review` agent — the
   `dev-loops:review` persona in scoped angle-review mode
   (`agents/review.agent.md`, generated to `.claude/agents/review.md`),
   spawned via the plain Agent tool, NOT a general-purpose agent — per
   resolved dispatch unit (`resolveFanoutGroups`), each given only its
   compact `dispatchPrompt`: the one-line instruction to run
   the pull CLI with concrete values (the emitted 3-flag line, or the short
   line `dev-loops-run scripts/github/pull-work-order.mjs <executionIdentity>`,
   ADR 0115). The reviewer runs it
   and follows the pulled work order, which references the identical neutral
   evidence and carries its angle prompts — unchanged from draft/
   pre-approval fan-out; no new reviewer angles, no bespoke review agent.
4. **Phase 3 — fan-in + post.** `node scripts/loop/consolidate-fanin.mjs
   --gate review [...] --emit-plan <emit-plan-path> --ledger-out <path>`
   synthesizes the per-angle findings into one disposition ledger and computed
   verdict (`<emit-plan-path>` is the keyed `review-<headSha>.emit-plan.json`
   sibling `emit-fanout-dispatch.mjs` persisted in Phase 2, consumed by the
   fan-in's `GATE-EXEC-EMIT-PLAN-KEY` fail-closed round-key guard — a stale or
   foreign emit plan fails closed instead of being consumed).
   **Phase 3.5 — judge.** Run it on the fan-in ledger after `consolidate-fanin.mjs`
   and before the durable ledger write and the post. The rule and its
   judge-spec line are owned by `REVIEW-GATE-JUDGE-PHASE` in the
   [Checkpoint Verdict Comment Contract](../docs/gate-review-comment-contract.md#review-gate-judge-phase);
   the spec precedence is owned by the
   [Spec Authority Contract](../docs/spec-authority-contract.md). A ledger with zero
   findings skips this phase and posts with no `--judge-spec-source`.
   1. Read the PR description and its closing issues through
      `node scripts/github/view-pr.mjs --repo <owner/repo> --pr <n> --json body,closingIssuesReferences`
      (never raw `gh`). Write the body to `<body-path>` with `--jq '.pr.body'`.
      The closing issues are `closingIssuesReferences`; when that list is empty,
      they are the issues named by `Closes`/`Fixes`/`Resolves #N` keywords in the PR
      body, the same resolution `resolveLinkedIssuesFromPr` applies in Phase 1.
      Each closing issue carries its repository: a `closingIssuesReferences` entry has
      `repository.owner.login` and `repository.name`, a body keyword matches only a bare
      `#N`, which is in the PR repository.
   2. Resolve the spec in this order, with `--head-sha <sha>`, `--content-file
      <reviewed-content-path>`, `--spec-out <spec-path>` and `--identity-out
      <identity-path>` on each call: (a) exactly one closing issue (as resolved in step 1): `node
      scripts/loop/spec-context.mjs --repo <issue-owner/issue-repo> --issue <closing-issue> ...`
      with the closing issue's own repository (`specSource: "issue"`); when that call exits 1 because the issue body has
      no formal spec, or when the PR has zero or several closing issues, go on to
      (b). The no-formal-spec signal is a stderr JSON with no `code` field and an
      `error` starting `spec body has no`; several closing issues are never merged. (b) `node
      scripts/loop/spec-context.mjs --repo <owner/repo> --body-file <body-path> ...`
      returns `specSource: "pr_body"`, `"pr_scope"` or `"none"`. Every other
      `spec-context.mjs` failure in (a) or (b) (a `code: "RATE_LIMITED"` envelope, a
      fetch error, an unreadable `--content-file`) never falls through: post the
      review unjudged with `--judge-spec-source unavailable --judge-unavailable-reason
      judge_failed`, never aborted.
   3. When `specSource` is `none` (no usable PR scope), do not run the judge. Post
      with `--judge-spec-source none`.
   4. Otherwise run the lifecycle judge path with `--gate review`:
      `node scripts/loop/emit-judge-work-order.mjs --gate review --repo <owner/repo> --pr <n> --head-sha <sha>
      --findings-file <ledger-out-path> --spec-file <spec-path> --identity-file <identity-path>`, dispatch the `judge` agent with
      the printed `dispatchPrompt` (pull transport), then `node scripts/loop/judge-pass.mjs --gate
      review --repo <owner/repo> --pr <n> --judge-plan <plan> --findings-file <ledger-out-path> --judge-verdict <path>
      --spec-file <spec-path> --content-digest <digest> --spec-authority-verdict <path>
      --head-sha <sha>`. Pass no `--out` and no `--ledger-out`: the durable write in
      step 6 reads the pre-judge `<ledger-out-path>` and re-applies the judgment itself. The review
      gate never feeds a fixer, and `judge-pass` posts no deferral comment, so a `defer`
      finding is recorded on the review body and in the findings log only.
   5. When `judge-pass.mjs` exits 1 (the judge failed, or returned
      `spec_cannot_decide`), never abort the post. Post the review unjudged with
      `--judge-spec-source unavailable --judge-unavailable-reason spec_cannot_decide`
      (the judge-pass stdout carries `humanDecisionRequired: true`) or `judge_failed` (any other failure). Every
      finding stays visible in its normal track.
   6. When the judge succeeded, write the durable ledger in the paragraph below (it
      reads the pre-judge `--findings-file <ledger-out-path>` and re-applies the judgment
      from the judged-round flags) and post with `--judge-spec-source <issue|pr_body|pr_scope>`. Missing formal
      acceptance criteria or definition of done is never an `act` finding and never
      blocks review completion; it shows only as the informational note on the judge-spec line.

   After Phase 3.5 and before posting,
   write the durable ledger through `node scripts/github/write-gate-findings-log.mjs` with
   `--findings-file <ledger-out-path> --execution-mode fanout_fanin`, plus
   `--judge-verdict <path> --spec-authority <identity-path>` on a judged round.
   The writer derives provenance from the keyed
   fan-in ledger (pass no `--emit-plan` or `--provenance`). Then `node
   scripts/github/upsert-checkpoint-verdict.mjs --repo <owner/repo> --pr <n>
   --gate review --head-sha <sha> --findings-ledger <path> [--judge-spec-source <source> [--judge-unavailable-reason <reason>]] --submit <mode> [--auto]
   [...]` posts the SINGLE visible PR review surface
   (`GATE-COMMENT-SINGLE-SURFACE`) straight from that ledger — no CI wait, no
   coordination-context read, no auto-resolve, no forbidden-action check
   (those are draft/pre-approval-only machinery `review` never touches). `--next-action` is optional on the `review` gate; any value passed is ignored, and the gate derives the next action from the judge act list (`GATE-COMMENT-REQUIRED-FIELDS`). See
   [Checkpoint Verdict Comment Contract](../docs/gate-review-comment-contract.md#review-gate-submit-modes-1840)
   for the `--submit` vocabulary. `approve`/`request-changes`/`discard`
   additionally REQUIRE `--interactive-confirm` (#1888/#1912) — fail closed
   unless provably interactive, so omitting `--auto` is not a license for a
   headless caller. When an own same-head pending review already exists,
   `comment`/`request-changes`/`approve` SUBMIT it via `/reviews/<id>/events`
   (preserving inline comments) rather than creating a second review (which
   422s); `discard` DELETES it (#1912).

   <!-- rule: REVIEW-GATE-VERDICT-CANONICAL -->
   `REVIEW-GATE-VERDICT-CANONICAL`: the `review` verdict MUST be posted through
   `upsert-checkpoint-verdict.mjs --gate review --findings-ledger <path>`
   (above) and MUST NOT be posted with a raw `gh pr review` or `gh api
   .../reviews` call. A raw post skips the `dev-loops:gate-findings-review
   review <sha> round=<n>` marker (`buildReviewHeaderMarker`,
   `_gate-finding-surface.mjs`) and every inline finding comment, so a reader
   cannot tell a contract-compliant round from a hand-authored comment that
   merely looks like one. The dev-loop skill's gh-only fallback poster
   ([Fallback gate-comment poster](../dev-loop/SKILL.md#fallback-gate-comment-poster))
   exists ONLY for the missing-`@dev-loops/core` case — it is not a
   convenience substitute for `review` when the full helper is reachable, and
   it does not even accept `--gate review` today.
   `audit-review-marker-presence.mjs` (`scripts/github/`) is a standalone, advisory-only check that
   flags a posted round missing the marker (or, when a `--findings-ledger`
   carries locatable findings, missing inline comments) with a WARNING; it
   never blocks and never becomes gate evidence — running it is optional, not
   part of this skill's own procedure.
5. **Phase 4 — submit choice.**
   - **Interactive:** post `--submit pending` first, then present `AskUserQuestion`.
     Every submit choice re-runs `upsert-checkpoint-verdict.mjs --gate review` (repeating the Phase 3.5 judge flags of the first post)
     for the SAME round, without another fan-out. It consumes the caller's own
     same-head pending review through `/reviews/<id>/events`, preserving inline
     comments and the review id; never create a second review.
     - **Leave pending (default):** print the review URL and how to finish it
       (open the URL or re-run the helper with the submit flags below). Warn
       that the draft remains invisible to other reviewers.
     - **Submit as Comment:** `--submit comment`, event `COMMENT`.
     - **Submit as Request-changes:** `--submit request-changes --interactive-confirm`,
       event `REQUEST_CHANGES`. Explain that this can BLOCK merge under GitHub
       branch protection until dismissed, independently of dev-loops gates.
     - **Submit as Approve:** `--submit approve --interactive-confirm`, event
       `APPROVE`. Explain that this SATISFIES required-approvals branch protection,
       independently of dev-loops gates; it never supplies lifecycle-gate evidence.
     - **Discard:** `--submit discard --interactive-confirm` deletes the caller's
       own pending draft (`DELETE /pulls/<pr>/reviews/<id>`), leaving no review.
     `--interactive-confirm` records the human's choice in this prompt;
     approve/request-changes/discard fail closed without it and refuse headless
     execution, including `--auto` with the token. Submit leaves one review,
     leave-pending keeps one draft, discard leaves none.
   - **`--auto`/headless:** post `--submit comment` and skip the prompt.

**Stop here.** After the post and the submit choice, never proceed to the fix cycle, a re-gate
round, `pr ready-for-review`, or a board move — a `review` round is a single,
complete, terminal pass. There is no `review` fixer loop and no re-gate path;
if the operator wants findings fixed, that is a SEPARATE, explicit
instruction, not something this skill initiates itself.

## Non-evidence, by construction

A `review` verdict is never `draft_gate`/`pre_approval_gate` evidence, in any
`--submit` mode. `parseGateReviewCommentFields` recognizes the `review` header
and returns `null`, with or without a findings marker. The parser reads the gate
name only from a labeled gate field line, never from free text. Preserve that
header: findings mentioning lifecycle gate names must not become evidence.

GitHub-native `APPROVE` can satisfy required approvals and `REQUEST_CHANGES` can
block merge independently. The interactive choice above owns their confirmation
boundary; omitting `--auto` does not establish human confirmation.

## Non-goals

No fixer loop, no re-gate, no merge path, no new reviewer angles, and no
headless CLI that spawns reviewers itself — fan-out stays agent-orchestrated
exactly like draft/pre-approval fan-out. It does not change draft_gate or
pre_approval_gate semantics in any way. No auto-submit of a pending review on
a later run — the human submits it (or discards it) via the interactive
submit choice.
