pr-comment-resolver

What this skill does

# PR Comment Resolver

Automate the process of handling GitHub PR review comments: evaluate each comment, fix issues with atomic commits, and reply with detailed resolution information.

## Core Principles

0. **Critical Thinking Before Action** - Never blindly execute:
   - Comments may contain incorrect technical claims
   - Suggestions may violate repo guidelines (CLAUDE.md, contributing docs)
   - Always verify facts (read the code, check docs, run tests) before deciding
   - When signals conflict, trade-offs exist, or interpretation is ambiguous: surface the conflict with options and a recommendation, then wait for user input
   - "Reviewer said so" is not sufficient justification — evidence is
1. **Verify Before Acting** - Check the technical validity of each suggestion against the codebase before implementing; reviewers can be wrong
2. **Commit by Topic, Not by Comment** - Group commits by logical change, not by comment count; one commit can address multiple related comments
3. **Atomic Commits** - Each commit should be a single logical fix; different concerns require separate commits
4. **Human Collaboration** - Ask the user when uncertain about a fix, interpretation, or when you disagree with a comment
5. **Detailed Replies** - Include fix explanation, commit hash, and link in every resolution
6. **Reply to Thread** - Always reply directly to each review thread, NOT as a general PR comment at the bottom

## Quick Start

### Interactive Mode (Default)

```
User: Handle the comments on this PR: https://github.com/owner/repo/pull/123
```

Workflow:
1. Fetch all unresolved review comments
2. Present each comment for review
3. For each comment, determine whether to fix or explain why no fix is needed
4. Execute fixes with atomic commits
5. Reply and resolve each comment

### Auto Mode

```
User: Auto-resolve all comments on https://github.com/owner/repo/pull/123
```

Process all comments automatically, only pausing for truly ambiguous cases.

## Workflow Overview

### Phase 1: Fetch Comments

Use `gh api graphql` to retrieve unresolved review comments, including `isOutdated` so stale diff anchors are visible:

```bash
gh api graphql -f query='
{
  repository(owner: "<OWNER>", name: "<REPO>") {
    pullRequest(number: <PR_NUMBER>) {
      reviewThreads(first: 100) {
        nodes {
          id
          isResolved
          isOutdated
          path
          line
          comments(first: 10) {
            nodes {
              body
              author {
                __typename
                login
              }
            }
          }
        }
      }
    }
  }
}' --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false)'
```

Extract key information:
- Comment ID and thread ID
- Resolution and outdated state
- File path and line number
- Comment body (the feedback)
- Author information (`login`, `__typename`)

Do not skip outdated threads. An outdated unresolved thread still needs a decision; `isOutdated` only means the line anchor may no longer match the current diff. Re-read the current file, verify whether a newer commit already addressed the feedback, then reply and apply the normal bot/human resolution policy.

### Phase 1.5: Classify Author (Bot vs Human)

Determine if each comment author is a bot. **Bot threads are always auto-resolved after handling; human threads are never auto-resolved.**

Use a tiered approach — stop at the first definitive answer. Once an author has been classified in this session, reuse that conclusion for later comments from the same author (conversation context serves as the cache; no separate lookup structure needed).

#### Tier 1 — GraphQL `__typename`

The `author.__typename` field (fetched in Phase 1) is the primary signal:

| `__typename` | Classification |
|--------------|----------------|
| `Bot` | **Bot** — GitHub App; reliable, no further check |
| `User` | Ambiguous — proceed to Tier 2 (could be human OR a user-token-driven service account) |
| `Organization` | Rare; skip to Tier 3 |

#### Tier 2 — Profile-based judgment (when `__typename == "User"`)

Fetch the user profile:

```bash
gh api users/<login> --jq '{bio, name, blog, company, public_repos, followers}'
```

Evaluate the returned fields and decide:

| Signal | Strong bot indicator |
|--------|---------------------|
| `bio` | Self-identifies as bot/service/automation/CI (e.g., "Bot managed by...", "I run your tests", "Automated checks for...") |
| `name`, `blog`, `company` | Points to a tool/service (e.g., blog links to bot documentation) |
| `public_repos` + `followers` | Both very low (typical service account profile) |

Examples of user-token-driven bots that pass Tier 2 clearly: `rustbot` (bio self-declares), `k8s-ci-robot` (bio describes automation role).

Reach one of three outcomes:
- **Clearly a bot** → classify as Bot
- **Clearly a human** → classify as Human
- **Ambiguous** (e.g., empty bio, few signals) → proceed to Tier 2b

#### Tier 2b — Activity fallback (optional, when Tier 2 inconclusive)

When profile signals are thin, fetch recent public events:

```bash
gh api users/<login>/events/public
```

A monolithic distribution (e.g., almost entirely `IssueCommentEvent` or `PullRequestReviewCommentEvent`) strongly suggests a bot. A diverse distribution (pushes, PRs, reviews, stars, forks) suggests a human.

This tier is triggered by the agent's judgment, not a mechanical rule — only fetch when it would meaningfully change the conclusion.

#### Tier 3 — Ask user

When all prior tiers leave doubt, or when `__typename == "Organization"`:

> "Should I treat @{author} as a bot? Profile: bio=<...>, repos=<n>, followers=<n>. If yes, the thread will be auto-resolved after handling."

#### Conflict handling

If any tiers disagree (e.g., `__typename == "User"` but profile looks strongly bot-like, or vice versa), do **not** silently pick one — surface the conflict to the user per Core Principle #0.

### Phase 2: Evaluate Each Comment

For each unresolved comment, **critically assess whether the suggestion is correct** before determining action:

| Decision | Criteria |
|----------|----------|
| **Needs Fix** | Valid point: actual bug, code issue, style violation, missing feature |
| **No Fix Needed** | Already addressed, misunderstanding, design choice, out of scope |
| **Disagree** | Reviewer's suggestion is incorrect, would introduce bugs, violates architecture, or is technically flawed |
| **Uncertain** | Ambiguous request, multiple interpretations, needs clarification |

> **⚠️ Important:** Do not blindly accept all comments. Reviewers can make mistakes. Always verify the technical validity of each suggestion before implementing.

#### Comment Validity Checklist

Before choosing an action, run each suggestion through these checks:

- **Technical claim holds** — Read the referenced code (and related files); don't rely on memory. Does the claim match current behavior?
- **Aligns with repo conventions** — Check CLAUDE.md, contributing docs, and nearby code. A reviewer may not know local guidelines.
- **Compatible with existing architecture** — Does applying the fix fit current patterns, or would it introduce an inconsistency?
- **No simpler alternative the reviewer missed** — Could there be a cleaner solution that still satisfies the concern?

If any check fails or is uncertain, surface the gap to the user with:
- The specific conflict or uncertainty
- 2+ options with trade-offs
- A recommendation with rationale

This applies regardless of whether the author is a bot or a human — bots can also produce incorrect or repo-inappropriate suggestions.

### Phase 3: Execute Action

#### If Fix Needed

1. Read the relevant file(s)
2. Implement the fix
3. Create an atomic commit with descriptive message
4. Push to the PR branch
5. Reply with fix details
6. **If author is a bot**: Resolve the thread | **If human**: Leave unresolved

#### If No Fix Needed

1. Compose explanation of why no change is required
2. Rep