/handling-pr-comments

name: handling-pr-comments
description: Address PR review feedback systematically — fetch inline comments, review bodies, handle outside-diff-range comments, resolve threads with proper attribution

handling-pr-comments

Use when addressing PR review feedback, after receiving review comments from CodeRabbit, Cursor, or human reviewers - ensures systematic responses to each comment thread with proper attribution and thread resolution.

When to Activate

Activate this skill when ANY of these conditions are true:

• User asks to "address PR comments" or "handle review feedback"
• User mentions CodeRabbit, Cursor bot, or reviewer comments
• User is working on fixes requested in a PR review
• User asks to "check PR comments" or "respond to reviewers"
• After making fixes to address review feedback

CRITICAL: The Complete Workflow

**Most developers forget steps 4-6. This skill ensures they happen.**

Phase 1: Discover and Filter Comments

Run the filtering script to identify actionable comments:

# Filter actionable vs non-actionable comments
bin/pr-comments-filter.sh <PR_NUMBER>

This script:

• Filters out non-actionable comments (confirmations, acknowledgments, fingerprinting)
• Categorizes actionable comments by priority (Critical → Low)
• Shows comment IDs and details for processing

Phase 2: Triage Actionable Comments

The filter script categorizes by priority:

| Priority | Marker | Action | | --------------- | -------------------------------------------------------- | ---------------- | | CRITICAL | `_⚠️ Potential issue_ \| _🔴 Critical_` | Fix immediately | | HIGH | `_⚠️ Potential issue_ \| _🟠 Major_` | Fix before merge | | MEDIUM | `_🟡 Minor_` or `_🛠️ Refactor suggestion_ \| _🟠 Major_` | Should fix | | LOW | `_🔵 Trivial_` / `_🧹 Nitpick_` | Fix if quick | | HUMAN | Non-bot comments | Always process |

For each actionable comment, further categorize as:

1. **Bug/Issue** - Must fix 2. **Enhancement** - Should fix 3. **Nitpick** - Nice to fix 4. **Question** - Needs clarification 5. **Intentional** - Decline with explanation 6. **Out-of-Scope** - See Phase 2b

Phase 2b: Extract "Outside Diff Range" Comments from Review Bodies (CRITICAL)

**COMMONLY MISSED**: CodeRabbit posts "Outside diff range" comments in the **review body**, not as inline threads. These are actionable feedback that MUST be addressed.

# Extract Outside diff range comments from review bodies
PR_NUMBER=<number>
OWNER=$(gh repo view --json owner -q .owner.login)
REPO_NAME=$(gh repo view --json name -q .name)

echo "=== OUTSIDE DIFF RANGE COMMENTS ==="
gh api "repos/$OWNER/$REPO_NAME/pulls/$PR_NUMBER/reviews" --paginate | \
  jq -r '.[] | select(.body | test("Outside diff range"; "i")) |
    "Review ID: \(.id)\n\(.body)\n---"'

**These comments are NOT in threads** - they cannot be replied to inline. You must:

1. Parse the file paths and line numbers from the review body 2. Address the feedback in your code 3. Commit and push 4. Leave a general PR comment acknowledging you addressed them

Phase 2c: Handle Other Out-of-Scope Comments

Run the out-of-scope detection script:

# Detect out-of-scope comments
bin/pr-comments-out-of-scope.sh <PR_NUMBER>

This script detects comments that:

• Reference lines NOT in the PR diff
• Are marked "outdated" by GitHub (GraphQL `isOutdated` flag)
• Are general PR discussion comments

**IMPORTANT**: Treat out-of-scope comments as **IN SCOPE** by default.

Evaluation Process

Use **ultrathink** to evaluate each out-of-scope comment:

ultrathink: Analyze this out-of-scope review comment:
- What is the reviewer asking for?
- How complex is this change? (lines of code, files affected)
- Does it require refactoring other systems?
- Can I complete this in under 30 minutes?
- Are there any risks or dependencies?

Recommend: FIX_NOW or CREATE_ISSUE

Decision Matrix

| Criteria | Action | | --------------------------------------------- | ----------------------------------------- | | Simple fix (< 30 min, < 3 files, no refactor) | **FIX_NOW** - Make the change immediately | | Medium complexity (unclear scope) | **ASK_USER** - Present options | | Major refactor (multiple systems, risky) | **CREATE_ISSUE** - Document for follow-up |

For FIX_NOW

1. Make the fix 2. Commit with descriptive message 3. Push to the PR branch 4. Reply: "Fixed in commit <hash>. This was outside the original PR scope but straightforward to address." 5. Resolve the thread

For CREATE_ISSUE

1. Create GitHub issue with context 2. Reply: "Created issue #<number> to track this." 3. Resolve the thread

Phase 3: Make Fixes

Fix the actual code issues. Commit and push.

Phase 4: RESPOND TO EACH THREAD (Often Forgotten!)

**After pushing fixes, respond to EACH comment thread individually:**

PR_NUMBER=<number>
OWNER=$(gh repo view --json owner -q .owner.login)
REPO_NAME=$(gh repo view --json name -q .name)
CURRENT_USER=$(gh api user -q '.login')
COMMENT_ID=<id-from-filter-script>

gh api "/repos/$OWNER/$REPO_NAME/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies" \
  -X POST \
  -f body="Fixed in commit $(git rev-parse --short HEAD).

*(Response by Claude on behalf of @$CURRENT_USER)*"

Phase 5: Resolve ALL Threads

**Every thread must be resolved after responding.** Use GraphQL to resolve:

THREAD_ID="PRRT_kwDOK-xA485..."  # From GraphQL query

gh api graphql -f query='mutation {
  resolveReviewThread(input: {threadId: "'"$THREAD_ID"'"}) {
    thread { id isResolved }
  }
}'

Phase 6: Handle Threads That Can't Be Resolved

1. **Query the comment author** asking for