pr-review-loop

What this skill does

# PR Review Loop

## Purpose

Address all open PR review comments one at a time using an opinionated, resumable workflow. Works with comments from any reviewer (human or bot).

## Typical invocations

Users trigger this skill with prompts like:

- "Address all open review comments on this PR"
- "Work through the code review feedback on PR #42"
- "Fix the review comments left by @alice on this pull request"
- "Use pr-review-loop on PR #123"

## Prerequisites

- `gh` CLI (preferred). If unavailable, fall back to any tool available to interact with GitHub.
- The PR branch must be checked out locally.

## Process

### Step 1 — Pre-flight

Inspect the project for safeguard conventions by checking these files (if they exist):
- `CLAUDE.md`, `AGENTS.md`
- `Makefile`
- `.github/workflows/`
- `README.md`

Identify all required safeguards (tests, compilation, linting, formatting, etc.).
Run all of them. If any fail, stop immediately and report — do not proceed on a broken baseline.

### Step 2 — Get Current PR Number and Basic Info

```bash
# Get current PR details
gh pr status

# View PR with all comments
gh pr view
```

### Step 3 — Collect All Unresolved PR Feedback

GitHub surfaces reviewer feedback in two distinct forms — both must be collected:

| Type | Where it lives | Has "resolve"? |
|------|---------------|----------------|
| **Review threads** | Inline comments anchored to a file/line, submitted as part of a review | Yes — `resolveReviewThread` mutation |
| **Issue comments** | Regular PR conversation comments (e.g. a summary review posted as a top-level comment) | No — reply serves as closure |

**Fetch review threads** (keep only unresolved ones):
```bash
gh api graphql -f query='
query($owner:String!, $name:String!, $number:Int!) {
  repository(owner:$owner, name:$name) {
    pullRequest(number:$number) {
      reviewThreads(first:100) {
        nodes {
          id
          isResolved
          path
          line
          comments(first:20) {
            nodes {
              id
              databaseId
              author { login }
              body
              createdAt
              replyTo { databaseId }
            }
          }
        }
      }
    }
  }
}' -f owner='{owner}' -f name='{repo}' -F number={pr_number} \
  | jq '.data.repository.pullRequest.reviewThreads.nodes | map(select(.isResolved == false)) | map(. + {type: "review-thread"})'
```

**Fetch issue comments** (top-level PR conversation comments):
```bash
gh api repos/{owner}/{repo}/issues/{pr_number}/comments \
  | jq '[.[] | {id: .id, author: .user.login, body: .body, created_at: .created_at, type: "issue-comment"}]'
```

> Before triaging, filter out comments by the PR author (they are not reviewer feedback) and known bot accounts. The `author` field in the transformed output helps with this.

Triage items from both lists. Track which type each item is — it affects how you reply (Step 5f) and close (Step 5g).

### Step 4 — Triage
Read [the triage guide](references/triage-guide.md) for the specific classification framework and examples. If the guide is not available, use the MUST_FIX / SHOULD_FIX / PARK / OUT_OF_SCOPE / NEEDS_CLARIFICATION classification with your own judgment (see definitions below).

Classify every unresolved comment as: MUST_FIX, SHOULD_FIX, PARK, OUT_OF_SCOPE, or NEEDS_CLARIFICATION.

Triage all comments before acting on any.

If a comment is non-actionable/no-op (e.g. acknowledgment, praise, emoji-only), classify as OUT_OF_SCOPE and reply with a short acknowledgment before resolving.

If a comment's intent is genuinely ambiguous — multiple interpretations exist and each would lead to a meaningfully different change — classify as NEEDS_CLARIFICATION rather than guessing.

If Perplexity or other research tools are available and a comment requires external knowledge to classify (e.g., library idioms, language conventions), use them to inform your decision.

### Step 5 — Process ONE comment at a time

Process in order: all MUST_FIX first, then SHOULD_FIX.
Skip PARK and OUT_OF_SCOPE for now (they are handled in the summary).

**NEEDS_CLARIFICATION comments:** post one focused question as a reply to the thread (see format below), do **not** resolve the thread, and move on to the next comment. Do not implement anything.

**Cascading comments:** When multiple comments form a cascade (e.g., changing a trait signature requires updating all impls, callers, and tests), group them into a single commit referencing all comment IDs. Implement the full cascade atomically — applying any single comment without the others would leave the code in an inconsistent state.

For each comment (or group of cascading comments):

**5a. Assess complexity**

Is this trivial (e.g., rename a function, fix a typo, adjust formatting)?
- Yes → fix directly, no plan needed
- No → create a plan file at `.pr-review/plan-<comment-id>.md` before touching any code

The plan file must describe:
- What the comment is asking for
- The approach to fix it
- Files that will be changed

**5b. Run safeguards**

Run all safeguards identified in Step 1. They must all pass before you touch any code.
If they fail, stop and report.

**5c. Fix, park, or ask for clarification**

- Fix: implement the change
- Fix with adaptation: if the reviewer's suggestion is directionally right but the exact code won't compile or is otherwise infeasible, implement the closest working alternative. Document the constraint in your reply (Step 5f) so the reviewer understands why the implementation differs from their suggestion.
- Park (if you discover mid-fix that it should be parked): write reasoning, revert any partial changes, no commit
- Ask for clarification (if you discover mid-assessment that the intent is genuinely ambiguous): post one focused question to the thread (see below), do not resolve, no commit, move on

**Clarification question format (for NEEDS_CLARIFICATION or mid-assessment uncertainty):**

```bash
cat > /tmp/pr-review-reply-{comment_id}.md <<'EOF'
Thanks for the feedback! Before I make a change, I want to make sure I understand what you're after:

<one specific, focused question — e.g. "Did you mean to rename this everywhere, or just at the call site?" or "Would you prefer approach A (…) or approach B (…)?">
EOF

jq -n --rawfile body /tmp/pr-review-reply-{comment_id}.md '{body:$body}' > /tmp/pr-review-reply-{comment_id}.json

gh api repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies \
  --input /tmp/pr-review-reply-{comment_id}.json
```

Ask exactly **one** question. Do not list alternatives unless directly needed to frame the question. Leave the thread unresolved so the reviewer's answer re-surfaces it.

**5d. Run safeguards again**

Run all safeguards. They must all pass.
If they fail, fix the regression before moving on — do not skip this step.

**5e. Commit and push**

Each comment gets its own focused commit. Reference the comment author in the message body.

```bash
git add <changed files>
git commit -m "<conventional commit message describing the fix>

Addresses PR comment from @<reviewer>."
git push
```

Example commit flow across multiple comments:
```bash
# Comment 1: Add missing documentation
git commit -m "docs: add module-level documentation for MetricsRecorder

Addresses PR comment from @reviewer about missing module docs."
git push

# Comment 2: Use Duration instead of i64
git commit -m "refactor: use Duration type for timing parameters

Addresses PR comment from @reviewer - improves type safety."
git push
```

**5f. Reply to the PR comment**

Post a reply explaining:
- What was done (for fixes: reference the commit)
- Why it was parked (for deferred items)
- Why it was rejected (for out-of-scope items)

The reply mechanism differs by comment type:

**For review thread comments** (inline, anchored to a file/line):
```bash
cat > /tmp/pr-review-reply-{comment_id}.md <<'EOF'
<reply text>
EOF

jq -n --rawfile body /tmp/pr-review-reply-{comment_id}.md '{body:$body}'