PR Triage

Fetch PR review comments and give an opinionated triage so you know exactly what to act on, what to skip, and what to push back on.

When to Use

• User shares a GitHub PR URL and asks for comment review
• User asks "pull the comments", "what does copilot think?", "go through the review"
• User wants to know which comments are worth fixing before merge
• After opening a PR, to prep responses before addressing feedback

Do not use this for:

• Writing new PR comments
• Reviewing the PR code — use gap-check + pre-ship on the branch
• Merging the PR — gh pr merge

Preflight — confirm the PR context

Before fetching, establish:

1. PR state — open, draft, closed, merged? Closed/merged PRs still have reviewable history; drafts may not have comments yet.
2. Reviewer set — humans only, bots only (Copilot, CodeQL, renovate), or mixed? Affects triage tone.
3. Target branch — main vs a feature branch? Merge urgency differs.
4. CI status — passing, failing, in-progress? Failing CI is itself a finding even if no human has commented yet.
5. Your role — are you the PR author or a reviewer triaging someone else's? Affects whose voice to draft replies in.

Collect these upfront via gh pr view before Phase 2 fetches comments.

Steps

Phase 1 — Authenticate

gh auth status 2>&1 | head -5

If gh not authenticated: gh auth login. If a GitHub MCP server is configured (check ~/.claude/settings.json), prefer it — structured output, less parsing. Otherwise fall back to gh CLI.

Phase 2 — Fetch all comments

A GitHub PR has three types of comments. Pull all three:

PR_URL="{{user-provided url}}"
# Parse owner/repo/number from URL: https://github.com/org/repo/pull/123

# (1) Issue comments — top-level conversation
gh api "repos/{owner}/{repo}/issues/{number}/comments"

# (2) Review comments — inline line-by-line
gh api "repos/{owner}/{repo}/pulls/{number}/comments"

# (3) Reviews — batched review objects with summary + body
gh api "repos/{owner}/{repo}/pulls/{number}/reviews"

If the GitHub MCP is available, prefer mcp__claude_ai_Github_MCP__pull_request_read or equivalent. Paginate if > 100 comments.

Phase 3 — Categorize

Read each comment with its file/line context. Assign one of four categories:

• [🐛 Bug — fix now] — genuine code issue, security gap, crash risk, broken contract, incorrect behavior. Must fix before merge.
• [💡 Legit improvement] — valid suggestion, would make code better but not a blocker. Sometimes deferrable.
• [📘 By design — skip] — intentional decision the reviewer didn't have full context for. Not a bug. Needs a reply comment, no code change.
• [❓ Needs discussion] — ambiguous, depends on product direction, or reviewer is pointing at real tension the author didn't decide on. Needs user input.

Edge cases:

• Copilot "nit" comments (style, naming, minor refactors) → usually [💡 Improvement], sometimes [📘 By design] if the codebase has an established pattern Copilot contradicts.
• Copilot false positives (suggests fixing correct code, misreads async flow) → [📘 By design] with explanatory reply.
• LGTM / +1 comments → exclude.
• Author self-comments (notes-to-self) → exclude.

Phase 4 — For each actionable comment

For [🐛 Bug] and [💡 Improvement]:

• Explain the issue in plain terms — synthesize, don't just quote
• State the fix specifically — not "handle the edge case", but "add null check at line 42"
• Estimate effort: Quick (< 5 min), Medium (15–30 min), Involved (> 30 min, may need design discussion)
• Note cross-dependencies — if fixing #3 also resolves #7, say so

For [📘 By design — skip]:

• Explain the intent
• Draft a 2–3 sentence reply comment the user can post to close the thread politely

For [❓ Needs discussion]:

• Explain the tension
• Suggest a question for the user to ask the reviewer, or a decision to make

Phase 5 — Produce the report

# PR Triage — {{PR title}}

**URL:** {{pr url}}
**Comments fetched:** {{N}} (issue: X, review: Y, reviews: Z)
**Reviewers:** {{names/bots}}

## 🐛 Bugs — fix before merge ({{count}})
1. **[reviewer]** `file:line` — "comment excerpt ≤150 chars"
   - **Issue:** [synthesis]
   - **Fix:** [concrete action]
   - **Effort:** Quick / Medium / Involved

## 💡 Improvements — worth doing ({{count}})
...

## 📘 By design — reply and close ({{count}})
1. **[reviewer]** `file:line` — "comment excerpt"
   - **Why it's fine:** [explanation]
   - **Suggested reply:** "[draft text]"

## ❓ Needs discussion ({{count}})
1. **[reviewer]** `file:line` — "comment excerpt"
   - **Tension:** [what's unresolved]
   - **Question for you:** [what to decide or ask]

## Summary

- **Bugs to fix:** {{count}}
- **Improvements worth doing:** {{count}} (~{{total}} effort)
- **Skipping as by-design:** {{count}} ({{N}} reply comments needed)
- **Needs your call:** {{count}}

## Recommended order
1. Fix bugs
2. Reply to by-design threads
3. Discuss/decide on open questions
4. Implement improvements (if not blocking merge)

Phase 6 — Ask which to act on

Do not auto-fix or auto-reply. Offer:

• (A) Fix all bugs + post all suggested replies — fastest path to merge
• (B) Fix bugs only, defer replies — user posts replies manually
• (C) Show me each one individually — for PRs where tone/context matters

Output Format

See Phase 5. Rules:

• Reviewer name on every item
• File:line when inline
• Comment excerpt ≤ 150 chars
• Effort tags only on actionable items (🐛, 💡)
• Suggested reply text in quotes, copy-paste ready

Rules

1. Don't fix during triage. Read-only. User approves separately.
2. Ambiguity → Needs discussion. Don't guess bug-vs-design — wrong guesses waste reviewer time.
3. Respect reviewer tone. Don't escalate if a reviewer is frustrated.
4. Don't suggest replies for 🐛 Bugs. Bugs get fixed, not explained away.
5. Group by category, not reviewer or file. Users want to know what to do.
6. Zero comments? Say so. Clean PR is a valid result — don't pad.
7. If gh and MCP both unavailable, stop and tell the user. Don't scrape the PR page.
8. If PR is closed/merged/draft, note that — affects what to do.
9. Copilot rule: Copilot over-suggests style changes. Downgrade style-only Copilot comments to 💡 or 📘 unless they align with a real codebase convention.
10. In subagent / headless mode, emit the report and stop. Do not post replies, do not implement fixes. The calling agent or user handles Phase 6 decisions.

Worked Example — Output

# PR Triage — Add team invites to onboarding

**URL:** https://github.com/example/app/pull/472
**Comments fetched:** 11 (issue: 2, review: 9, reviews: 2)
**Reviewers:** @alice, @bob, @copilot[bot]

## 🐛 Bugs — fix before merge (2)

1. **[alice]** `src/api/invites/create.ts:42` — "The `sendEmail` call isn't
   wrapped in try/catch — if Resend fails, we already inserted the invite
   but return 500."
   - **Issue:** Partial failure leaves DB inconsistent; user has no retry path.
   - **Fix:** wrap `sendEmail` in try/catch, mark row `email_pending` on
     failure, schedule retry via `src/workers/email-retry.ts`.
   - **Effort:** Medium (~20 min)

2. **[copilot]** `src/pages/invite/[token].tsx:18` — "Token from URL used
   without validation; `useUser(token)` will throw on malformed input."
   - **Issue:** Real bug. Malformed URL crashes the page.
   - **Fix:** validate with `z.string().uuid()` before hook; show 404.
   - **Effort:** Quick (~5 min)

## 💡 Improvements — worth doing (3)

3. **[alice]** `src/components/InviteButton.tsx:15` — "Add `aria-label` for a11y."
   - **Fix:** `aria-label="Invite team member"`.
   - **Effort:** Quick (~1 min)

4. **[bob]** PR-level — "Would be nice to have a rate limit."
   - **Fix:** apply existing `rateLimit(50, '1h')` middleware.
   - **Effort:** Quick (~5 min)

5. **[copilot]** `src/lib/emails/invite.ts:30` — "Template string could use
   backticks instead of concatenation."
   - **Fix:** template literal.
   - **Effort:** Quick (~2 min)

## 📘 By design — reply and close (2)

6. **[copilot]** `src/api/invites/create.ts:28` — "Consider extracting email
   validation into a utility."
   - **Why it's fine:** 3-line zod schema used in one place. Extracting at
     one call site is premature.
   - **Suggested reply:** "Thanks — this is only used here, extracting at a
     single call site would be premature. Happy to revisit if we add a
     second caller."

7. **[bob]** PR-level — "Should this be in a feature flag?"
   - **Why it's fine:** Spec says unconditional rollout. Flag would be state
     we'd immediately remove.
   - **Suggested reply:** "Per the spec this is an unconditional launch —
     not gated. A flag would add state we'd remove next week."

## ❓ Needs discussion (2)

8. **[alice]** `src/db/schema.ts:45` — "Why `org_id` on invite but not
   `inviter_id`? Audit trail?"
   - **Tension:** Audit is valid but not in spec. Cheap to add but changes
     schema mid-PR.
   - **Question for you:** Bundle `inviter_id` in this PR (~30 min extra)
     or follow-up PR?

9. **[bob]** PR-level — "Should invites expire?"
   - **Tension:** Product decision. Affects schema (`expires_at`) and cron.
   - **Question for you:** Confirm with product: expire, how long?

## Summary

- **Bugs to fix:** 2 (~25 min)
- **Improvements worth doing:** 3 (~10 min)
- **Skipping as by-design:** 2 (2 reply comments needed)
- **Needs your call:** 2 (audit column, expiration policy)

## Recommended order

1. Fix bugs #1, #2 — 25 min
2. Reply to #6, #7 — 5 min
3. Decide with product on #8, #9
4. Apply #3, #4, #5 — 10 min
5. Request re-review from @alice, @bob

Pipeline Position

write-plan → plan-review → (implement) → gap-check → simplify → pre-ship → (deploy)
                                                                            ↓
                                                                       [pr-triage]

PR triage happens after opening a PR for review and reviewers have weighed in. Run it when sitting down to address feedback — batches the work, prevents per-comment thrash.