SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsrespond-to-review

respond-to-review

Coding & development

View repository

Updated 10-28 14:46

About this skill

Respond to Review

Take a teammate's review of your PR, check each comment's claim against the code with a reader who did not write it, let the human decide what happens to each one, hand the fixes to /fix-findings, draft the pushback, and leave a record in the project's sidecar to come back to.

Why this skill exists

On a team, most PRs get a human review after /pre-merge has stamped them. Before this skill, the pack had no route for that review. /pre-merge writes .claude/.review-stamped beside its stamp, the post-review edit lock then refuses implementation edits unless /fix-findings is running, and /fix-findings accepted only findings from a /pre-merge run. A teammate's comment was neither, so the only way to act on it was to delete the lock by hand and fix in the session that wrote the code.

Sending those comments straight into /fix-findings would have been the wrong repair. Its fixer is briefed to fix, and reports refuted only when the tree flatly contradicts a claim. A comment that is accurate but wrong in judgment, a preference phrased as a requirement, or a request outside the PR's scope would all get fixed. Most review comments are not defects in the first place. Rigby's finding is that contemporary review is discussion, not defect logging. So this skill puts a step in front of the fix seam: check whether the claim is true, then let the human decide. Cohen's verification loop says a fix has to be checked. This skill checks the defect before anyone fixes it.

The check runs in a fresh sub-agent because the session that wrote the code is the one context with a stake in the answer. A fixer leans toward fixing. An author leans toward defending. The evidence check leans toward neither.

Invocation Position

Side-route, HITL only. It fires when a human reviewer exists, so solo work never reaches it. Enter it:

  • from /closeout Step 2, when the PR's reviewDecision is CHANGES_REQUESTED or it has unresolved review threads;
  • from /help, which recommends it on the same signal;
  • by typing /respond-to-review (current branch's PR) or /respond-to-review <pr-number>.

It is model-invocable so those routes can run it rather than only name it. The cost is its description in every session's context. What gates it is the input: a PR with review threads, and a human in the session who asked to respond. Never run it on an AFK iteration. There is nobody to decide the threads, so there is no valid output.

It reconnects at /fix-findings → /pre-merge re-run → /closeout, the path /pre-merge's own findings already take.

What this skill is NOT

  • It does not decide. The evidence check records what it found, never what should happen. A thread marked refuted is evidence for the human, and pushing back is still the human's call. A thread the human does not name stays open. It is never defaulted to any disposition.
  • It does not post, reply, or resolve. Reply drafts print to the terminal for the human to edit and post. Nothing in this skill writes to the PR.
  • It does not fix. Threads marked fix go to /fix-findings, which keeps its own fresh fixer, breaker, cap, and handoff unchanged.
  • It does not stamp and does not merge. /pre-merge is the stamp's only writer and /closeout is the only thing that merges.
  • It writes nothing in the project's tree. Its one durable output is the record in the sidecar.

Workflow

Step 1. Read the review, word for word

Resolve the PR: the number the human gave, or the current branch's PR (gh pr view --json number -q .number). Then read its unresolved review threads and its non-empty review summaries in one GraphQL call. The block numbers them in time order and keeps every comment body exactly as written:

PR=<pr-number>
THREADS_JQ='
[inputs][0] | if (.errors // [] | length) > 0 then "unknown" else
.data.repository.pullRequest as $p
| if $p == null or $p.number != $n
     or ($p.reviewThreads.nodes | type) != "array"
     or ($p.reviews.nodes | type) != "array"
     or ($p.reviewThreads.nodes | length) != $p.reviewThreads.totalCount
     or ($p.reviews.nodes | length) != $p.reviews.totalCount
     or ([$p.reviewThreads.nodes[] | select((.comments.nodes | length) != .comments.totalCount)] | length) > 0
  then "unknown"
  else
    ($p.author.login // "") as $me
    | ([$p.reviewThreads.nodes[]
        | select(.isResolved | not)
        | select((.comments.nodes[0].author.login // "") != $me)
        | {kind: "thread", id, path, line, outdated: .isOutdated,
           url: .comments.nodes[0].url, at: .comments.nodes[0].createdAt,
           last_at: .comments.nodes[-1].createdAt,
           comments: [.comments.nodes[] | {author: (.author.login // "ghost"), body, url, at: .createdAt}]}]
       + [$p.reviews.nodes[]
        | select((.body // "") != "" and (.author.login // "") != $me)
        | {kind: "review", id, state, url, at: .submittedAt, last_at: .submittedAt,
           comments: [{author: (.author.login // "ghost"), body, url, at: .submittedAt}]}])
    | sort_by(.at)
    | {pr: $p.number, state: $p.state, head: $p.headRefOid, head_ref: $p.headRefName,
       items: (to_entries | map(.value + {n: (.key + 1)}))}
    | tojson
  end
end'
RESP=$(gh api graphql -F owner='{owner}' -F repo='{repo}' -F n="$PR" -f query='
  query($owner: String!, $repo: String!, $n: Int!) {
    repository(owner: $owner, name: $repo) {
      pullRequest(number: $n) {
        number state headRefOid headRefName author { login }
        reviewThreads(first: 100) { totalCount nodes {
          id isResolved isOutdated path line
          comments(first: 50) { totalCount nodes { author { login } body url createdAt } } } }
        reviews(first: 100) { totalCount nodes { id state body url author { login } submittedAt } }
      }
    }
  }') || RESP=null
jq -rn --argjson n "$PR" "$THREADS_JQ" <<<"${RESP:-null}" || echo unknown

It prints one JSON object, or the single word unknown.

  • unknown means gh failed, the response carried errors, the PR did not come back, or a list came back shorter than its own totalCount. Re-run once. If it is still unknown, tell the human and stop. Never evaluate a short read: a missing thread looks exactly like a thread that was never written.
  • What is left out, and why. Resolved threads are settled. Threads and reviews the PR's author started are the author's own notes, not feedback. Review summaries with an empty body are only the containers GitHub makes for inline comments, which arrive as threads.
  • What is kept. Outdated threads (the line moved, but the comment may still stand, and the evidence check says which) and bot reviewers. The human decides what a bot's comment is worth, not this block.
  • Bounds. It reads up to 100 threads, 100 reviews, and 50 comments per thread, and says unknown rather than silently truncating past them.
  • On a forge gh cannot reach the call fails and the block prints unknown. This skill is GitHub-only for now.

If the PR's state is not OPEN, say so and stop. If head_ref is not the current branch, the evidence check can still run, but say before Step 5 that fixes need the PR's branch checked out.

When the record already exists, read it first (Step 4 says where it lives). Its thread markers say which items an earlier round already settled:

SC="<this skill's directory>/references/sidecar.sh"
REC="$(bash "$SC" path review-responses)/pr-<pr-number>.md"
[ -f "$REC" ] && awk '
  match($0, /^<!-- thread: id=[^ ]+ last-at=[^ ]+ disposition=[^ ]+ -->$/) {
    split(substr($0, 6, length($0) - 9), f, " ")
    sub(/^id=/, "", f[2]); sub(/^last-at=/, "", f[3]); sub(/^disposition=/, "", f[4])
    seen[f[2]] = f[3] " " f[4]
  }
  END { for (id in seen) print id, seen[id] }' "$REC" | sort

Each line is <thread-id> <last-at> <disposition> for the latest round that recorded that thread. An item whose id appears with the same last_at, and whose disposition is not open, is settled. Show it with its earlier disposition, and leave it out of the evidence check. An item that is new, or whose last_at moved because someone replied, gets the full check. On a miss the resolver says why (no sidecar, typically). Carry on without a prior round, and Step 4 says what happens to the record.

For threads disposed fix in an earlier round, read what landed from the tree, not from memory. /fix-findings ends each teammate-sourced fix commit with a Review-Thread: <url> line:

SC="<this skill's directory>/references/sidecar.sh"
BASE_REF="$(bash "$SC" base-ref)" || { echo "base-ref failed: not guessing a base" >&2; exit 1; }
git log --format=commit.%H%n%B "$BASE_REF..HEAD" \
  | awk 'length($0) == 47 && /^commit\.[0-9a-f]+$/ { sha = substr($0, 8, 7) } /^Review-Thread: / { print sha, $2 }'

Step 2. Check each claim in a fresh sub-agent

Spawn one read-only sub-agent on the cheaper tier (model: "sonnet") for every unsettled item. One for the batch, not one per thread: it gathers evidence and decides nothing, and threads often refer to each other. A fixer carrying one fix's reasoning into the next is the risk /fix-findings guards against per finding. An evidence reader seeing two related comments together is not that risk.

The context contract is /pre-merge Phase 3's (read it there, under The context contract is about provenance, not permission), with this skill's inputs:

  • Handed over: the items' JSON exactly as Step 1 printed it, the PR diff (gh pr diff <pr-number>), and references/comment-craft.md, especially § Receiving a review.
  • Reached for itself: the merged tree, git log and git show, tests and their output, installed types, docs/solutions/.
  • Withheld absolutely: this session's reasoning about the code, and its opinion of the comments. That is the stake the sub-agent exists to remove. Do not summarize a comment for it. Hand it the comment.

It must not edit, stage, commit, or write anywhere, and it must not post to the PR. It returns one row per item, in exactly one of these categories:

Category Means Must carry
supported the claim holds in the tree the file:line, test, or command output that shows it
refuted the tree contradicts the claim the file:line, test, or command output that contradicts it
preference no objective justification (5P Ponder) what kind of justification would have made it a requirement
out-of-scope valid, but not this PR's change (5P Postpone) what the PR's change is, and where the concern lives instead
discussion a question or remark with no claim to check nothing; say what is being asked

Check its citations before presenting. For every supported and refuted row, confirm the cited path exists and the cited line range is within the file. Re-label a row whose citation does not resolve as unverified — <the citation>. A wrong refuted sends the author to push back on a correct comment, and that costs more than any other error this step can make.

When sub-agents are unavailable, run the check in-session and name it degraded mode in the presentation. The evidence comes from the session that wrote the code, so read every refuted with that in mind.

Step 3. The human decides each thread

Present one table, settled items included:

# Where Comment (first line) Evidence Earlier round

Write the Evidence cell to the reader bar in /pre-merge Phase 4. Name the thing in domain terms and lead with the claim. When one thread's choice forks three or more ways with three or more attributes each, compare them first, following references/next-step-menu.md § Show the comparison before you take the choice.

Then ask one question: which threads to fix, push back on, postpone, or answer yourself. Take the answer as typed, for example fix 1 3; push back 2; postpone 4; answer 5. Repeat back any number given twice or not at all. An item not named is recorded as open. Never assign it a disposition.

Disposition What this skill does with it
fix hands it to /fix-findings in Step 5
push back drafts a reply per references/comment-craft.md § Receiving a review: Triple-R, the evidence as Rationale, the tone rules, a signal prefix if the team uses them
postpone drafts a follow-up issue body and a one-line reply saying it was split out. The human files the issue (/qa is the pack's intake for it)
answer nothing unless asked. The human replies. If asked, draft from the evidence row

Reply drafts carry no pack vocabulary. They are posted under the human's name on a PR the team reads, and on a guest repo that PR is the client's. No skill names, no Fix-Findings-Run or Review-Thread lines, no W- ids, no "the evidence check found". Write as the author, citing code.

Step 4. Write the record to the sidecar

The record is the author's durable, off-GitHub account of this review, for coming back to it later. It lives in the project's sidecar, a private local-only git repository outside the working tree, at the path sidecar.sh computes, and it is committed there. Write it before Step 5: /fix-findings ends in its own menu and nothing returns control here, and on a first round its fallback source, this record, would not exist yet:

SC="<this skill's directory>/references/sidecar.sh"
REC="$(bash "$SC" path review-responses)/pr-<pr-number>.md" || exit 1
# Append this round to "$REC" (create it with the header on the first round).
bash "$SC" commit -- "$REC" -m "review-responses: PR <pr-number>, round <k>"

Append a round, and never rewrite an earlier one:

# Review responses — PR <pr-number>

## Round <k> — <YYYY-MM-DD>, head <short-sha>

<!-- round: k=<k> head=<full-sha> evidence=<sub-agent|degraded> -->

### <n>. <path>:<line> (or: review summary, <state>) — <url>

<!-- thread: id=<thread-id> last-at=<last_at> disposition=<fix|push-back|postpone|answer|open> -->

> <each comment, verbatim, quoted, with its author and date>

- **Evidence:** <category> — <citation>
- **Disposition:** <disposition>
- **Reply draft:** <the draft, or "none">
- **Compound candidate:** <yes — what the pack's own review missed | no>

Marker values are literal, with no angle brackets. A > inside an HTML comment ends the naive <!-- … --> read that Step 1's awk performs. /pre-merge's ledger learned that on its first test run. Thread ids, ISO timestamps, and the five disposition words never contain one.

A compound candidate is a thread that is supported and marked fix. A teammate found a real defect that the pack's own review let through, and that escaped class is exactly what /compound captures. Mark it in the record and name it in the handoff below. Do not run /compound from here.

With no sidecar, path fails and prints the resolver's reason. Print the round to the terminal, say it was not persisted, and offer /init-pipeline to create a sidecar. Never fall back to a file in the project's tree. On a guest repo that file would land in the client's repository.

Step 5. Hand the fixes to /fix-findings

If any thread is marked fix, invoke /fix-findings with exactly those numbers. Hand it each item's JSON verbatim, which carries the comment bodies and the thread URL, and the Step 2 evidence row beside it. The human's typed disposition is the selection /fix-findings requires. This skill adds no number to it, and drops none from it. /fix-findings takes it from there: a fresh fixer per thread, which may still report refuted, a breaker, one Review-Thread: <url> line per commit, and its own handoff to a /pre-merge re-run.

If no thread is marked fix, skip this step.

Handoff

  • Expected input: an open PR on GitHub with a teammate's review, and the human who will decide each thread.
  • Produces: an evidence row per unsettled thread, the human's disposition for each, reply drafts for pushback and postponed threads, a /fix-findings run on the threads marked fix, and a review-response round in the sidecar.
  • Comes next by default: when threads went to /fix-findings, its own handoff (a /pre-merge re-run that reviews the fixes and re-stamps), then /compound when the record names a compound candidate, then /closeout once the PR is approved. With no fix threads: the human posts the replies, and /closeout once the PR is approved.

Next-step menu. When /fix-findings ran, its menu is the handoff, and this skill adds none. Otherwise offer one AskUserQuestion (see references/next-step-menu.md), recommended first: → Post the replies yourself, then /closeout once approved (recommended), Show the reply drafts again, Stop here — the record is in the sidecar. When the record names a compound candidate, add /compound the escaped defect first. The platform's free-text "Other" is the escape hatch. Do not add one.

Print the runtime handoff line:

**Next session:** /respond-to-review <pr-number>
**Input:** the teammate's next round on PR <pr-number> — the sidecar record carries the settled threads