pr-review-handler

What this skill does

# PR Review Handler

Systematically processes PR review comments: assesses each piece of feedback, creates a coherent action plan, implements changes, and responds to reviewers.

---

## Flow

```mermaid
flowchart TD
  A["A: Input — PR URL + Spec Path"] --> B
  B["B: Fetch unresolved comments via gh"] --> C
  C["C: Parallel sub-agents assess each comment"] --> D
  D["D: Synthesize assessments into action plan"] --> E
  E["E: Present plan to user for approval"] --> F
  F{"F: User approves?"}
  F -->|Yes| G
  F -->|No, with edits| E
  F -->|Abort| Z
  G["G: Execute actions"] --> H
  H["H: Test, lint, format"] --> I
  I["I: Commit and push"] --> J
  J["J: Draft responses for user review"] --> K
  K["K: Post responses to PR"] --> L
  L["L: Output — Summary"]
  Z["Z: Exit"]
```

---

## Input

- **PR URL**: GitHub PR URL (e.g., `https://github.com/org/repo/pull/123`)
- **Spec file path**: Path to the spec being implemented (provides intent context)

---

## Step 1: Fetch Comments

Run the `fetch-comments.sh` script from the same directory as this SKILL.md:

```bash
bash <plugin_dir>/fetch-comments.sh <PR_URL>
```

This script uses the GitHub **GraphQL API** (the only way to get `isResolved` status on review threads). It handles pagination and outputs structured JSON to stdout.

### Output Format

```json
{
  "pr": {
    "number": 123,
    "state": "OPEN",
    "title": "Feature X",
    "url": "https://github.com/org/repo/pull/123",
    "headRefName": "feature/x",
    "baseRefName": "main"
  },
  "unresolvedThreads": [
    {
      "id": "PRRT_abc123",
      "path": "src/foo.ts",
      "line": 42,
      "startLine": null,
      "diffSide": "RIGHT",
      "isOutdated": false,
      "firstCommentDatabaseId": 12345678,
      "comments": [
        {
          "databaseId": 12345678,
          "body": "This needs a null check",
          "author": "reviewer1",
          "createdAt": "2026-04-10T12:00:00Z",
          "diffHunk": "@@ -40,6 +40,8 @@..."
        }
      ]
    }
  ],
  "topLevelComments": [
    {
      "databaseId": 87654321,
      "body": "Overall looks good but...",
      "author": "reviewer2",
      "createdAt": "2026-04-10T11:00:00Z"
    }
  ],
  "reviewBodyComments": [
    {
      "databaseId": 11111111,
      "body": "Something broke with the transition...",
      "state": "CHANGES_REQUESTED",
      "author": "reviewer2",
      "createdAt": "2026-04-10T09:00:00Z"
    }
  ],
  "meta": {
    "totalThreads": 15,
    "unresolvedThreads": 5,
    "resolvedThreads": 10,
    "topLevelComments": 3,
    "reviewBodyComments": 1
  }
}
```

### Key fields for later steps

- **`firstCommentDatabaseId`** on each thread — the ID needed to post replies via REST API (used in Step 8)
- **`path`** and **`line`** — file location for reading the relevant code
- **`isOutdated`** — true if the code has changed since the comment was made; see Step 2 for handling
- **`comments`** array — contains the full conversation thread. Check for prior responses (especially ones starting with `🤖 *Addressed via Claude Code*`) to avoid re-handling work that's already been done
- **`topLevelComments`** — general PR discussion not tied to specific code lines; these need assessment too (see Step 2)
- **`reviewBodyComments`** — the high-level text reviewers write when submitting a review (e.g., "Changes requested: ..."). These often contain important feedback like bug reports or blocking concerns that aren't tied to specific code lines. Easy to miss — always check these

---

## Step 2: Assess Comments

### Pre-assessment: Triage for prior responses

Before doing detailed assessment, scan each thread's `comments` array for existing responses. A thread has already been handled if:
- It has a reply starting with `🤖 *Addressed via Claude Code*` (from a prior run of this skill)
- The reviewer has NOT posted further objections after that reply

Threads that were previously addressed but have new reviewer follow-ups after the response DO still need assessment — the follow-up is the thing to assess, not the original comment.

This triage matters because PRs often go through multiple review rounds. Re-handling already-addressed threads wastes time and can produce confusing duplicate responses.

### Assessing threads that need it

Spawn a sub-agent for each thread that wasn't filtered out by triage. Each sub-agent receives:
- The comment thread (full context)
- The relevant code snippet
- The spec file (for understanding intent)
- Other comments on the same file (for awareness)

**Verify factual claims.** When a reviewer makes a factual assertion (e.g., "this API doesn't exist", "this method is deprecated", "this will crash"), check the actual source code or documentation before accepting it. Reviewers — including automated ones like Copilot — can be wrong. Read the relevant source, check type definitions, or look at upstream docs. Getting this right avoids making unnecessary changes or introducing regressions based on incorrect claims.

**Handle outdated threads.** If `isOutdated` is true, the code has changed since the comment was made. Read the current code at the relevant path — the issue may have already been fixed by subsequent commits even though no one replied to the thread. Flag outdated threads in the action plan so the user knows which comments refer to stale code.

### Assessment Output

Each sub-agent returns one of:

**1. Needs Action**
```yaml
assessment: needs-action
summary: "Reviewer is right — we're not handling the null case"
suggested_fix: "Add null check before accessing user.profile"
file: "src/components/UserCard.tsx"
lines: [42, 45]
effort: trivial | small | medium  # helps prioritize
outdated: false  # true if isOutdated — flag in plan
```

**2. Needs Discussion**
```yaml
assessment: needs-discussion
summary: "Reviewer suggests Redux but spec explicitly chose Zustand"
reason: "unclear" | "disagrees-with-spec" | "out-of-scope" | "subjective"
suggested_response: "The spec chose Zustand for X reason. Happy to discuss if you feel strongly."
outdated: true  # flag so user knows this refers to stale code
```

**3. Already Resolved**
```yaml
assessment: already-resolved
summary: "This was fixed in a subsequent commit"
evidence: "Commit abc123 added the missing validation"
suggested_response: "Addressed in abc123 — added validation for empty arrays."
```

**4. Previously Addressed**
```yaml
assessment: previously-addressed
summary: "A prior Claude Code run already responded to this"
evidence: "Reply from @author on 2026-04-01 starts with '🤖 *Addressed via Claude Code*' — explained the file was not deleted. No reviewer follow-up."
```

Include the `outdated` field on every needs-action and needs-discussion assessment. When `outdated: true`, add `[OUTDATED]` to the action/discussion entry in the plan — this tells the user the comment refers to code that has since changed, so the fix may already be in place or the suggestion may no longer apply.

### Top-Level and Review Body Comments

Don't skip `topLevelComments` or `reviewBodyComments` — these contain PR-level feedback not tied to specific code lines.

**`reviewBodyComments`** are the text reviewers write when submitting a review (the "Changes requested" or "Approved" message). These frequently contain the most important feedback — bug reports, blocking concerns, or high-level design objections. A reviewer might write "Something also broke with the transition animation" in the review body while their inline comments focus on specific code issues. Missing the review body means missing the big picture.

**`topLevelComments`** are general PR discussion (issue-level comments). These include human feedback, CI bot reports, and test trigger commands.

For both, assess:
- Has the item been addressed in a subsequent comment or commit?
- Does it require investigation or a code change?
- Is it informational only (CI reports, bot messages)?

---

## Step 3: Synthesize Action Plan

A single agent reviews all assessments to create a co