/maintainer-review

name: maintainer-review
description: Review someone else's pull request as the maintainer deciding whether it merges.
disable-model-invocation: true
type: flow
license: MIT
metadata:
  version: "1.0"

Maintainer review

You are the merge gate, not the author's assistant: the question is whether this ships, and the contributor will argue back. Your own PR belongs to `self-review`. Review in **this** session, not a subagent. A session opened for the PR is fresh already, and staying in it keeps the diff, the comments and your findings in hand for the argument that follows. Session already loaded with unrelated work, say so and offer a fresh one first.

Before the first text addressed to the user, the report included, actually invoke [explain-in-simple-language](../explain-in-simple-language/SKILL.md) and follow it — reciting its rules from memory does not count. Not installed: plain words, one idea per sentence, and nothing named only by a stand-in the reader hasn't seen.

1. Start clean and current

A stale checkout reviews against yesterday's rules: the convention docs the diff pass runs as a checklist come from it, and so did whatever auto-loaded at session start.

Before the gather: `git fetch`. Fetch failed, say so and ask rather than compare against a stale ref. Then compare the checkout against the freshest ref of the branch it tracks, the repo's default branch when it tracks none. Behind it, say so and offer to fast-forward; the update is a write, so it waits for a go-ahead. A dirty tree does not cancel the offer; git refusing it, or a diverged tree, is reported, never resolved for the user. When the update touched the repo's agent-governing docs or anything they reference, re-reading them now does not replace what already loaded: recommend reopening the session on the new tip and re-invoking.

The checkout's position never decides the diff base: step 2 pins that from the PR. A PR targeting a branch other than the one checked out leaves the wrong docs on disk: say so and leave the call to the user, never switch the checkout yourself.

Done when the checkout is clean and on its freshly fetched tip, or you named what stands in the way (drift, a failed fetch, a base elsewhere) and the user chose to proceed.

2. Gather

Take a PR reference on any forge and pull, through whatever tooling is connected, **all** of it before judging: metadata (title, description, author, base and head refs, draft state, labels, mergeability, required-check results), the diff, and every comment stream — conversation comments, review verdicts with their bodies, and inline threads with their replies. A single "view PR" call typically misses the review bodies and the inline threads; expect one request per stream.

Fetch here, never via `fetch-pr-review`: it writes the author's triage file and takes thread status from the forge, which step 4 re-derives against the current head.

Fetch, then diff the merge base — `<base>...<head>`, three-dot — so the target's own commits don't read as the author's. A fork's head has no local ref; fetch the forge's PR ref for it. A fetch failing here, or a ref not resolving, say so and ask rather than judge a stale or wrong head.

Done when the head SHA, the base, the diff, the check results and all comment streams are in hand.

3. Follow every reference

Extract every issue and PR reference, commit sha, external link and domain identifier (a ticket key or product entity id) from the title, the description and **every** comment, then open each, including its own comments and the references it carries in turn, as far as the trail stays on this PR's subject. A linked issue's description is part of the requirement; a linked PR may already have fixed or superseded this one.

**Never take a claim as fact**, the author's no more than a reviewer's. "This breaks X" and "fixed in the latest push" are hypotheses until the code, the data, the cited source or the current target says otherwise.

An unticked box in the PR template is hygiene, not evidence: the sources are whatever the PR and the opened references actually hold, and weak or off-target evidence is named as such, never called absent.

Done when every reference on the PR, and every on-subject one it led to, has been opened or recorded as unreachable.

4. Walk every comment

Build an explicit list of every conversation comment, review body and inline thread including replies. For each, record what was raised, whether it was answered, and **whether it still applies at the current head and the current target**. A thread the target has since fixed counts as answered, by the commit and file that fixed it; an anchor that merely drifted onto changed lines has not been answered by anything.

Never skip one for looking resolved, old or minor, and never batch them away. Bot reviewers count: their findings are often the only ones on record, and an author's "no, addressed above" is a claim like any other.

An approval predating the current head approved a different changeset — say so rather than counting it.

Done when every item carries, with its evidence, whether it was answered and whether the concern still stands or no longer applies — answering one never settles the other.

5. Read the diff

Load [review-code-assistant](../review-code-assistant/SKILL.md) on the pinned changeset, its mandate reframed as the merge gate — does anything here block the merge. Take from it only *Review lenses* (the convention-docs checklist included), *Grounded, not speculative* and the list of what an explanation holds under *Output*, each explanation kept to step 7's short paragraph. Everything else there, comment handling and the *Output* section included, is superseded by steps 1 to 4 and 7 and by *Boundaries*: the changeset stays the step-2 head SHA, so the diff pass and the comment walk judge the same code, and the findings stay unprinted drafts until step 7.

Done when the diff pass has returned its findings, possibly none.

6