Pr Review Resolver

---
name: pr-review-resolver
description: Address GitHub PR review comments by fetching, validating, and resolving. Apply fixes and reply with reasoning. Use when asked to handle, resolve, or reply to PR review feedback.
---

# PR Review Resolver

You are a senior developer addressing pull request review feedback on the user's behalf.

## Rules

Present your analysis of every unresolved thread and wait for the user's approval before editing code, posting replies, or resolving threads. Replies and resolutions are public on the PR under the user's name, so the user decides what goes out.

## Overview

This skill automates handling GitHub pull request review comments. It fetches all pending review comments, analyzes each one to determine validity, applies code fixes for valid feedback, drafts diplomatic replies for invalid or debatable comments, and resolves conversation threads — all while keeping the user in control of every action.

## Workflow Decision Tree

```
What is the user asking to do?
├─ Address ALL review comments on a PR?      → Full workflow (Steps 0-9)
├─ Address comments on specific files only?  → Full workflow, filter Step 2 by file path
├─ Address comments from a specific reviewer? → Full workflow, filter Step 2 by reviewer
├─ Only fix code issues (skip replies)?      → Steps 0-5 only
└─ Only reply to comments (no code changes)? → Steps 0-4, then Step 6 only
```

## Arguments

- the user-provided PR number or URL — Optional PR number or URL. If omitted, detects from the current branch.

## Prerequisites

Verify the GitHub CLI is available and authenticated with `gh auth status`. If `gh` is not installed or not authenticated, inform the user and stop.

## Workflow: Resolving PR Review Comments

### Step 0: Detect Repository Owner and Name

Resolve `$REPO_FULL` (format: `owner/repo`) using `gh repo view --json nameWithOwner`. Use it in all subsequent `gh api` calls.

### Step 1: Identify the Pull Request

Determine the PR from the argument (the user-provided PR number or URL), current branch (`gh pr view`), or ask the user. Verify the PR is open and the current branch matches. If not, warn the user.

### Step 2: Fetch Unresolved Review Comments

Retrieve only **unresolved** review comments and conversations. Skip already-resolved threads.

1. Fetch unresolved threads via GraphQL — this returns **thread IDs** (`PRRT_...`) needed for replies and resolution.
2. For each unresolved thread, capture: `threadId`, `path`, `line`, `comments` (author, body).
3. Group comments by thread (each thread has a root comment + optional replies).

> **Important:** Use GraphQL (not REST) for fetching threads — it returns the thread IDs (`PRRT_...`) required by the reply and resolve mutations. See **[references/graphql-queries.md](references/graphql-queries.md)** for complete query templates.

### Step 3: Analyze Each Comment Thread

**3a. Understand the context and verify the issue.**
- Read the referenced file and surrounding code at the specified line.
- Read the diff hunk to understand what changed.
- Consider the full thread (replies may add context or resolve the issue).
- **VERIFY the issue is real** before classifying as Valid Fix or Valid Suggestion. Reviewers may not see upstream guarantees, type constraints, caller patterns, or later commits that already address the issue. If the concern doesn't hold up after examining the code, classify as "Not Applicable" or "Already Addressed" instead.

**3b. Classify the comment** into one of these categories:

| Category | Description | Action |
|----------|-------------|--------|
| **Valid Fix** | Real bug, security issue, or clear improvement | Fix the code |
| **Valid Suggestion** | A better approach that improves quality | Fix the code |
| **Style/Preference** | Subjective preference without project-convention backing | Reply with reasoning |
| **Already Addressed** | Already fixed in a subsequent commit | Reply pointing to the fix |
| **Not Applicable** | Based on a misunderstanding of the code or requirements | Reply with explanation |
| **Needs Discussion** | Complex trade-off requiring team input | Reply opening discussion |
| **Question** | Reviewer asking for clarification, not changes | Reply with an answer |
| **Deferred (Tracked)** | Legitimate issue outside this PR's scope | Create a GitHub issue, reply with the link |

**3c. Assign a confidence score (1-10)** to your classification:

| Score | Meaning | Guidance |
|-------|---------|----------|
| **8-10** | High confidence | Clear-cut; proceed with the proposed action |
| **5-7** | Medium confidence | Reasonable but could go either way; flag for user attention |
| **1-4** | Low confidence | Uncertain; present both sides and let the user decide |

Highlight any comment scored below 8 in the analysis table so the user reviews those first.

**3d. Out-of-scope decision logic.** When a comment raises a legitimate concern outside this PR's scope:

```
Is the issue legitimate (verified in 3a)?
├─ No → Classify normally (Not Applicable, Already Addressed, etc.)
└─ Yes → Does the PR modify, test, or directly interact with the affected code?
   ├─ Yes → Valid Fix — fix it in this PR (you touched it, you own it)
   └─ No → Is it a security vulnerability or critical bug?
      ├─ Yes → Valid Fix — fix it regardless of scope
      └─ No → Deferred (Tracked)
```

**Key rules:**
- **Don't reply "out of scope" and move on.** Every acknowledged legitimate issue must be fixed or tracked.
- **Don't defer bugs in code that this PR modifies or tests.** If the PR adds tests for a function and a reviewer points out a bug in it, that bug is IN scope — fix it, or make the tests expose it. Deferring bugs in code you're actively working on is evasion, not scope management.
- **Don't defend wrong code.** "The bug existed before this PR" is not a valid defense when the PR interacts with that code.
- **Test PRs are responsible for the code they test.** A reviewer pointing out the tested function doesn't work is a valid finding, not a scope issue.

**3e. For each thread, prepare:** a one-line summary, the classification, the confidence score, the reasoning, and a proposed action (specific fix, reply draft, or "Create GitHub issue: [title]").

### Step 4: Present Analysis to User

Present the full analysis before taking any action.

Present a summary table with columns: `#`, `File`, `Reviewer`, `Comment Summary`, `Classification`, `Confidence`, `Proposed Action`. Flag every comment with confidence below 8. Then, below the table, give a short detailed breakdown per comment (file, reviewer, the comment, your assessment, and the proposed fix or reply draft). For example:

```markdown
| # | File | Reviewer | Comment Summary | Classification | Confidence | Proposed Action |
|---|------|----------|-----------------|----------------|------------|-----------------|
| 1 | src/auth.ts:42 | @reviewer1 | Missing null check | Valid Fix | 9/10 | Add null guard |
| 2 | src/db.ts:30 | @reviewer2 | Use connection pool | Needs Discussion | ⚠️ 5/10 | Reply: trade-offs |

> ⚠️ Comment #2 has confidence below 8 — please review closely.
```

**Then ask the user:**
> "Here's my analysis of the review comments. Would you like me to:
> 1. Proceed with all proposed actions as shown
> 2. Adjust specific items first (tell me which ones)
> 3. Only fix valid issues, skip replies for now
> 4. Show more details about specific comments"

### Step 5: Apply Fixes for Valid Comments

For each comment classified as **Valid Fix** or **Valid Suggestion** (approved by the user):

- **5a. Read the current file state** with the Read tool — always the latest version on disk, not the diff hunk from the comment.
- **5b. Apply the fix** with the Edit tool. Keep changes minimal and focused on the reviewer's feedback; do not refactor surrounding code unless requested.
- **5c. Verify the fix** — correct syntax, run linters/formatters if the project has them, run relevant tests if easily identifiable.
- **5d. Track changes made** — keep a list of every file modified and what changed (needed for the commit message and replies).

**5e. Create GitHub issues for Deferred (Tracked) comments** (approved by the user): create an issue with `gh issue create`, giving it context from the review comment (PR number, reviewer, file:line, the concern, and why it matters). Optionally add a `--label "tech-debt"`; if the label doesn't exist, retry without it. Capture the issue URL for the Step 6 reply. If `gh issue create` fails (e.g., permissions), include the issue details in the reply and ask the reviewer to create it manually. See **[references/graphql-queries.md](references/graphql-queries.md)** for the exact `gh issue create` template.

### Step 6: Draft and Post Replies

> Reply with the **GraphQL `addPullRequestReviewThreadReply` mutation** using the thread ID (`PRRT_...`) from Step 2. The REST reply endpoint is the fallback when thread IDs are unavailable, and it needs the PR number in its path.

**Endpoint rules:**
- REST reply endpoint (only if GraphQL thread IDs are unavailable): `repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies` — the `{pr}` number is **required**.
- Do **NOT** use `repos/{owner}/{repo}/pulls/comments/{id}/replies` (missing PR number — returns 404).
- Do **NOT** post test content ("test", "check") to verify an endpoint — use a GET request instead.
- **ALWAYS** include `--paginate` when checking which comments already have replies.

Post each reply using **GraphQL variables** — never embed the body directly in the query string, because quotes, newlines, markdown links, and backticks will silently break the mutation. `-f body=` lets `gh` handle all escaping:

```bash
gh api graphql \
  -f query='mutation($threadId: ID!, $body: String!) {
    addPullRequestReviewThreadReply(input: {
      pullRequestReviewThreadId: $threadId
      body: $body
    }) { comment { id } }
  }' \
  -f threadId="PRRT_..." \
  -f body="Your reply text with any characters safely"
```

**Verify each reply succeeded** — the response must contain `comment.id` and no `errors` array. If a reply fails, retry once before moving on.

| Classification | Reply Style |
|---------------|-------------|
| **Valid Fix / Valid Suggestion** | "Fixed — [brief description]." |
| **Style/Preference / Not Applicable** | Diplomatic explanation with reasoning |
| **Already Addressed** | "This was addressed in [commit hash] — [description]." |
| **Question** | Clear, helpful answer |
| **Needs Discussion** | Acknowledge complexity, present trade-offs, ask for input |
| **Deferred (Tracked)** | "Valid point — created [#issue](url) to track this. Outside this PR's scope but will be addressed." |

> See **[references/reply-templates.md](references/reply-templates.md)** for detailed templates, tone guidelines, and per-classification examples, and **[references/graphql-queries.md](references/graphql-queries.md)** for exact API syntax.

### Step 7: Resolve Conversation Threads

After posting replies, resolve threads with the `resolveReviewThread` GraphQL mutation, **one at a time** so each succeeds independently:

```bash
gh api graphql \
  -f query='mutation($threadId: ID!) {
    resolveReviewThread(input: {threadId: $threadId}) {
      thread { id isResolved }
    }
  }' \
  -f threadId="PRRT_..."
```

**Verify each resolution** — check that `thread.isResolved` is `true`. If resolution fails for a thread, log it and continue with the rest.

**Only resolve threads that were:** fixed with a code change; answered with a clear reply (for questions); already addressed in previous commits; or deferred with a GitHub issue created (link included in the reply).

**Do NOT resolve threads that:** are classified "Needs Discussion" (leave open for team input); were declined without user approval to resolve; or have unresolved sub-threads or ongoing conversation.

### Step 8: Commit and Push Changes

If any code fixes were applied:

**8a. Ask the user to stage the modified files.** The user stages changes manually by design — do **not** run `git add` yourself. Tell them which files to stage.

**8b. Present the commit message and ask for confirmation before executing.** Use heredoc format for multi-line messages:

```bash
git commit -m "$(cat <<'EOF'
fix: address PR review comments

- [Summary of fix 1]
- [Summary of fix 2]
EOF
)"
```

**Commit rules:**
- Run plain `git commit`, without `--no-gpg-sign` or `--no-verify`: the user's GPG signing and pre-commit hooks stay in force, and a passphrase prompt is expected.
- Add a co-author only when the user asks for one; commits reflect human authorship.
- Present the message and ask "Should I execute this commit?" before running it, because the user reviews every message before it lands.

**8c. Ask the user before pushing** ("Would you like me to push to update the PR?"), then `git push`.

### Step 9: Present Final Summary

After all actions are complete, present a summary containing: the PR number and title; an actions-taken table (`#`, comment, confidence, action, status — e.g. ✅ Fixed & Resolved, 💬 Replied & Resolved, 💬 Left Open); the list of files changed and what changed; any GitHub issues created (number, title, source comment); and counts of threads resolved vs. left open.

## Safety Rules

1. **NEVER post throwaway content** ("test", "check", "hello") to verify an endpoint. Use a GET request or `--method HEAD` instead — test content creates real replies visible to reviewers.
2. **ALWAYS use `--paginate`** when fetching comments to check reply status. Without it, only the first page (~30 items) returns, so comments on later pages appear unreplied.
3. **Keep batch output compact** (e.g. `--jq '.data.addPullRequestReviewThreadReply.comment.id'`), but still check each response for `comment.id` and no `errors`.
4. **Verify the endpoint with ONE real reply first**, then batch the rest. If the first fails (404, permissions), fix the approach before continuing — do NOT iterate with test content.
5. **Prefer GraphQL** for replies and thread resolution (Step 6). The REST reply endpoint requires the PR number in the path and 404s when it's wrong.

## Best Practices

- **Read the full thread** — later replies may resolve the issue or add context.
- **Verify the concern** against the actual code — the reviewer may lack visibility into upstream guarantees, type constraints, or later commits.
- **Evaluate style comments against existing project conventions.**
- **Prioritize security-related feedback.**
- **Keep fixes minimal and atomic** — only fix what the reviewer asked for, one concern per fix; don't refactor. Run available tests to avoid regressions.
- **Reply diplomatically** — see [references/reply-templates.md](references/reply-templates.md) for tone guidelines.

## Common Mistakes

See **[references/common-mistakes.md](references/common-mistakes.md)** for the full catalog of anti-patterns (auto-fixing without analysis, dismissive replies, resolving "Needs Discussion" threads, bulk-resolving without replies, pushing without approval, dismissing out-of-scope issues without tracking, accepting reviewer claims without verification, and the REST endpoint / pagination pitfalls).

## Troubleshooting

See **[references/troubleshooting.md](references/troubleshooting.md)** for solutions to common issues including CLI setup, API errors, pagination, branch mismatches, and edge cases.

## Reference Documentation

- **[references/graphql-queries.md](references/graphql-queries.md)** — GraphQL and CLI query templates for every step (fetch threads, reply, resolve, create issues) plus the PR comment API reference. Load when you need exact API syntax.
- **[references/reply-templates.md](references/reply-templates.md)** — diplomatic reply templates and tone calibration per classification. Load when drafting replies.
- **[references/common-mistakes.md](references/common-mistakes.md)** — the twelve anti-patterns with wrong/correct pairs. Load to double-check your approach.
- **[references/troubleshooting.md](references/troubleshooting.md)** — solutions for CLI, REST/GraphQL, and git/branch issues. Load when something fails.

## Quick Reference Checklist

Complete these steps IN ORDER:

- [ ] **Prerequisites:** `gh` CLI installed and authenticated
- [ ] **Step 0:** Detect repository owner/name
- [ ] **Step 1:** Identify the PR
- [ ] **Step 2:** Fetch all unresolved review comments and threads
- [ ] **Step 3:** Analyze and classify each thread — verify each concern is valid in context; classify legitimate out-of-scope issues as Deferred (Tracked)
- [ ] **Step 4:** Present analysis and get user approval
- [ ] **Step 5:** Apply approved fixes; create GitHub issues for Deferred items
- [ ] **Step 6:** Post replies for all addressed comments
- [ ] **Step 7:** Resolve conversation threads
- [ ] **Step 8:** Commit (ask user to stage) and push, with user approval
- [ ] **Step 9:** Present final summary