/handle-pr-comments

/handle-pr-comments

Handle review comments on pull requests with appropriate responses and resolutions.

Usage

/handle-pr-comments <pr-number>

Overview

This command helps systematically address PR review comments from automated tools (like CodeRabbit) and human reviewers. It ensures consistent, professional responses that acknowledge the AI assistance.

---

CRITICAL: Complete PR Lifecycle Protocol

**A PR is NOT complete until ALL of the following are true:**

1. All CI checks pass 2. **EVERY** code review comment has been addressed (including trivial/nitpicks) 3. **EVERY** comment thread has received an individual response 4. All threads are marked as resolved (after reviewer approval) 5. Any work > 1 day has a GitHub issue created 6. No pending reviewer comments awaiting response 7. ALL tests pass, there are no pre-existing issues or flaky tests - these are excuses. Fix the underlying issues, don't disable tests. 8. **No new reviews after last commit with actionable items** (Section 1d)

Mandatory Comment Handling Rules

| Comment Type | Action | DO NOT Skip | | ---------------------- | -------------------------- | --------------------------- | | Critical/Major | Fix immediately | Never | | High/Medium | Fix before merge | Never | | Minor | Fix | Never | | **Trivial/Nitpick** | **FIX THESE TOO** | These matter! | | **Out-of-scope** | **INVESTIGATE THOROUGHLY** | Often the BEST insights! | | Human comments | Always address | Never |

Work Sizing Decision

For EACH comment:

• **< 1 day of work** -> Implement the fix in this PR
• **> 1 day of work** OR architectural change -> Create a new GitHub issue, link it in your response

Iteration Loop

REPEAT until (all_threads_resolved AND no_new_comments AND no_new_reviews_after_commit):
  1. Fetch ALL inline comments (including trivial, out-of-scope)
  1b. CHECK REVIEW BODIES for "Outside diff range" comments (Section 1c)
      - These are NOT threads - they're in the review body text
      - Commonly missed because they don't appear as threads!
  2. Check for NEW REVIEWS after last commit (Section 1d)
  3. For each comment: fix OR create issue OR respond with disagreement
  4. Run validation: lint, typecheck, and tests
  5. Commit and push
  6. Respond to EVERY thread individually
  6b. For "Outside diff range" comments: leave a general PR comment acknowledging
  7. CRITICAL: WAIT FOR CI/CD, then RE-CHECK for NEW comments/reviews
     - Monitor CI/CD pipeline: `gh pr checks $PR_NUMBER --watch`
     - Wait until ALL checks complete (not just pass - complete)
     - Automated reviewers (CodeRabbit) post comments during/after their check
     - Check BOTH inline threads AND review bodies for new feedback
     - Check for NEW REVIEWS with "Actionable comments posted: X" (X > 0)
  8. If new comments OR new reviews exist -> GO TO STEP 1
  9. If no new comments/reviews AND all checks complete -> verify all threads resolved, then complete

**THE #1 WORKFLOW FAILURE**: Stopping after responding without checking for new comments/reviews. **THE #2 WORKFLOW FAILURE**: Missing "Outside diff range" comments in review bodies.

Automated reviewers POST NEW COMMENTS after analyzing your fix commit. You MUST loop back. "Outside diff range" comments are in REVIEW BODIES, not threads. You MUST check them (Section 1c).

**Thread Resolution Policy**:

• Resolve when: code committed + responded + reviewer acknowledged
• Resolve immediately if declining a suggestion (with explanation)
• Never auto-resolve without reviewer acknowledgment

---

Cross-Platform Compatibility

**IMPORTANT**: This command is designed to work on both Windows (Git Bash) and Mac/Linux with automatic fallback logic.

**How it works**:

• **First choice**: Uses `jq` if available (more powerful, supports complex queries)
• **Fallback**: Uses `gh api -q` (GitHub CLI's built-in jq subset) for simpler queries
• Compatible with Windows Git Bash, Mac, and Linux
• No additional dependencies required beyond `gh` CLI (but `jq` is recommended for full functionality)

Rate Limit Considerations

GitHub has separate rate limits for REST API and GraphQL API:

• **REST API**: 5,000 requests/hour with PAT
• **GraphQL API**: 5,000 points/hour with PAT (complex queries cost multiple points)

This command uses **REST API exclusively** to avoid GraphQL rate limit issues. If you encounter rate limits, check both:

# Check REST API rate limit
gh api rate_limit -q '.rate'

# Check GraphQL API rate limit (separate from REST)
gh api graphql -f query='{ rateLimit { limit remaining resetAt } }' -q '.data.rateLimit'

Critical Workflow Notes

**IMPORTANT**: Comment IDs can change after you push commits. Always:

1. Get initial comment IDs 2. Make your fixes and commit 3. **RE-FETCH comment IDs** before posting responses (comments may have been updated/replaced) 4. Post responses to CURRENT comment IDs (not stale ones from before your commit) 5. **WAIT for reviewer confirmation** - Do NOT resolve threads immediately after your reply 6. Only resolve threads when: (a) reviewer confirms they're satisfied, OR (b) you're explicitly declining/ignoring the suggestion

**Resolution Policy**:

• **Wait for reviewer approval** before resolving addressed feedback
• **Resolve immediately** only if declining a suggestion (explain why in your reply)
• **Never auto-resolve** after posting a fix - let the reviewer verify

**Pattern**: Use GraphQL for thread operations (variables via -f/-F; parse with `-q` on fetch or `jq` for stored JSON) and REST for posting replies.

Workflow

1. Check for New Comments (Cross-Platform)

**Pattern**: Use GraphQL for thread operations (variables via -f/-F; parse