/refine-pr-review

name: refine-pr-review
description: Triage a fetched PR review with the user, comment by comment, drafting each reply and producing a REQUIREMENTS file for the accepted code changes. Takes the PR-REVIEW file produced by fetch-pr-review, or a PR URL. Invoke manually only.
license: MIT
metadata:
  version: "1.12"

Refine PR review

The **Refine** phase for review feedback: turn a `.PR-REVIEW.md` (from /fetch-pr-review; ask if the path is ambiguous) into user-settled per-comment verdicts, drafted replies, and a REQUIREMENTS file covering the accepted code changes. Triage and replies are settled here; the plan and execute phases see only code changes.

A PR URL instead: when the harness has subagents and fetch-pr-review is available (`../fetch-pr-review/SKILL.md` beside this skill), a subagent fetches it first per its [delegate.md](../fetch-pr-review/delegate.md) and the file it returns is the input. Not available → say so and ask for the fetched file; available but no subagents → hand off `/fetch-pr-review <url>` to a fresh session and stop.

A trailing `head=<sha>` token (fetch-pr-review's refresh hand-off) is the head a refresh just confirmed: Phase 1's moved-head check uses it in place of the file's `Head` line.

Its own `.PR-REVIEW.REQUIREMENTS.md` instead, once a blocking answer is in: run Phase 1's checkout and remote-head check first — a checkout differing from the ANSWERS `Head`, or a dirty tree, is reported and the user decides, never a branch switch; a moved PR head is reported with the re-fetch offer and the user decides whether to finish this round first. Verdicts, replies and Lessons stand as its `.PR-REVIEW.ANSWERS.md` records them. Apply the answer: every reply whose described change it alters is re-drafted under Phase 1's voice rule, confirmed, and updated in place; a verdict changes only as an explicit, user-confirmed exception to Phase 2's "Scope is settled in Phase 1"; a lesson whose source rows are no longer all accepted is put to the user; no row affected → the ANSWERS file is not rewritten. Then Phase 2 on that file, then Next step.

Verdicts

• **address**: the change enters the requirements in full; the reply stays a canned one-liner

("fixed", "good catch, thanks").

• **partial**: part of the change is accepted into the requirements, and the reply explains what

was done and what was kept and why.

• **push back**: no code change; the reply carries the reason.
• **no action**: no code change; a reply is optional (a question answered, an outdated concern the

current code settles, an approval with no ask, the author's own comment) — when written, it is drafted and shown like any other.

Bot findings take `bot: included` (reply "fixed"), `bot: partial` (Notes say which part; the reply names what was fixed and why the rest was not) or `bot: ignored` (reply: the reason, one short factual sentence, no thanks or hedging).

Naming a comment

Never refer to a comment by index or position, anywhere — questions, batch lists, hand-off text. Quote its opening words instead, truncated to the shortest unique prefix — the comment "the null check here misses …". Always verbatim, never translated or corrected, so the quote can be searched on the page. Only the ANSWERS table's own row numbers stay, for in-file cross-references.

Phase 1 — triage every comment with the user

Before the first code check, compare the checkout with the PR-REVIEW head: a different commit or branch, or a dirty tree, is reported and the user decides; never switch branches yourself. A PR head that moved since the fetch (the remote compared with the file's `Head`, or with the `head=<sha>` token when given) → offer a re-fetch before triage; a refresh (no new activity) keeps the file, the checkout still compared with the current head, and a refresh the URL path's fetch just reported needs no re-fetch. The URL path gets the same check — the subagent's fetch is seconds old, the checkout is still the user's.

On a `-N` file, read the earlier rounds' ANSWERS first: a comment re-raising one already triaged keeps its verdict and reply unless it brings evidence the earlier one lacked, and its Notes say `kept from round K, row M`; a kept row's work and lessons stay with round K, never counted as accepted below. An earlier round without ANSWERS was never triaged: its comments join this triage, each row's Notes saying `joined from round K`, its status read from the latest `## Since round` block listing it. A `-N` file with no touched thread (a Since block only) → say there is nothing to triage, list the status changes, write no ANSWERS or REQUIREMENTS file, print no launch command, stop. This round's ANSWERS file or REQUIREMENTS file already exists (and the REQUIREMENTS file is not the input) → one question before triage, covering both: **update in place** (recommended — existing rows stand, their verdicts and replies kept unless the user changes them or a comment brings new evidence; only new or changed comments are triaged) or **start over** (every comment re-triaged, both files replaced at write time). Never a second ANSWERS sheet; nothing overwritten without this answer.

Read the code behind each comment first: verify its premise against the checkout, never judging from the quoted hunk alone. Then form a recommendation — verdict, reasoning, and a draft reply for every verdict but address: partial, push back, and a `no action` reply that answers or explains, a courtesy reply on an outdated thread included. Before the first such draft in a round (even one with no partial or push-back row), actually invoke `use-conversational-language` (Developer conversations, author replies) and follow it; reciting its rules from memory does not count. Not installed: plain prose, no dashes and no AI tells. Every reply other than address's canned one-liner is shown to the user before it is written. Nothing is decided silently, and every question to the user is worded via `explain-in-simple-language` when availab