triage-pr-reviews

# Triage PR Review Comments

## Phase 1: Fetch and Analyze

1. Run `gh pr-reviews [arg] --json` to get unresolved review comments as JSON. If no argument is given, use the current branch's PR. Note: this command uses Copilot for classification and may take a while depending on the number of comments — use a longer timeout. Each JSON object contains:
   - `comment_id` (int): REST API comment ID — usable for replying via `gh api`
   - `thread_id` (string, only for `type: "thread"`): inline review thread ID
   - `type`: `"thread"` (inline review) or `"comment"` (PR-level)
   - `author`, `body`, `url`: comment metadata
   - `commit_id`, `path`, `line`, `diff_hunk` (only for `type: "thread"`): file location and diff context
   - `category`: one of `suggestion`, `nitpick`, `issue`, `question`, `approval`, `informational`
   - `resolved` (bool), `reason` (string): resolution status and rationale
   - `replies` (array, optional, only for `type: "thread"` with multiple comments): follow-up comments in the thread, each with `author`, `body`, `created_at`, `url`
2. Check if PR metadata (number, title, url) is already available from conversation context. If not (e.g., when a PR number/URL is explicitly passed as argument), run `gh pr view [arg] --json number,title,url` to get it.
3. For `type: "thread"` comments, use `path`, `line`, and `diff_hunk` from the JSON response to identify the exact file location. For `type: "comment"` (PR-level), there is no file location.
4. Check code context for each comment. Leverage any existing conversation context first. Only fetch additional context via `gh pr diff` or file reads when necessary.
5. Evaluate each comment against the code context. When a thread has `replies`, read the full conversation to understand whether the concern has already been discussed or partially addressed. Classify as **Agree**, **Partially Agree**, or **Disagree** with a rationale and suggested action.

## Phase 2: Summary Overview

Show a brief summary of all comments before starting the interactive walkthrough:

```
## Unresolved Review Comments — PR #<number> (<title>)

| # | Category | Author | Assessment | File |
|---|----------|--------|------------|------|
| 1 | <category> | @<author> | Agree/Partially Agree/Disagree | `<path>:<line>` |
| 2 | <category> | @<author> | Agree/Partially Agree/Disagree | `PR-level` |

Total: <count> comments — Agree: n, Partially Agree: n, Disagree: n

Walking through each comment below...
```

## Phase 3: Interactive Walkthrough (one-by-one)

For each comment, in order:

1. **Present the comment** in this format:

```
---
### [<current>/<total>] [<category>] by @<author>
> <comment body>

**File**: `<path>` (line <line>)   ← omit for PR-level comments
**Assessment**: <Agree | Partially Agree | Disagree>
**Rationale**: <1-3 sentences>
**Suggested action**: <recommended action>
```

2. **Ask the user what to do**. Present the following action choices and wait for the user's response before proceeding. The user may pick one of the predefined actions or provide free-text instructions:
   - For `type: "thread"` (inline review thread), offer:
     1. **Fix in code** — Make the code change only
     2. **Fix & reply & resolve** — Make the code change, post a reply, and resolve the thread
     3. **Fix & reply** — Make the code change and post a reply without resolving
     4. **Reply & resolve** — Post a reply comment on GitHub and resolve the thread
     5. **Reply only** — Post a reply comment on GitHub without resolving
     6. **Skip** — Move on without taking action
   - For `type: "comment"` (PR-level comment), offer:
     1. **Fix in code** — Make the code change only
     2. **Fix & comment** — Make the code change and post a PR-level comment
     3. **Comment only** — Post a PR-level comment on GitHub
     4. **Skip** — Move on without taking action
   - The user may select by number, name, or provide **custom instructions** (e.g., "fix but also refactor the surrounding function", "reply with a question asking for clarification", etc.)

3. **Execute the chosen action** — code fixes and commits are applied immediately during the walkthrough. **GitHub API actions (reply, comment, resolve) are deferred** to Phase 4 (ideally after pushing). During this phase, confirm the reply/comment content with the user and queue it for later execution. When an action includes a code fix, record the commit hash so it can be referenced in the queued reply/comment.
   - **Fix in code**: Make the code change, draft a commit message following the repository's commit message conventions (check `git log` for style), confirm it with the user, and commit.
   - **Fix & reply & resolve** (`type: "thread"` only): Make the code change, draft a commit message following the repository's commit message conventions (check `git log` for style), confirm it with the user, and commit. Ask the user what to reply (or suggest a draft reply) and confirm the content. Queue the reply and resolve for Phase 4.
   - **Fix & reply** (`type: "thread"`): Make the code change, draft a commit message following the repository's commit message conventions (check `git log` for style), confirm it with the user, and commit. Ask the user what to reply (or suggest a draft reply) and confirm the content. Queue the reply for Phase 4.
   - **Fix & comment** (`type: "comment"`): Make the code change, draft a commit message following the repository's commit message conventions (check `git log` for style), confirm it with the user, and commit. Ask the user what to comment (or suggest a draft) and confirm the content. Queue the comment for Phase 4.
   - **Reply & resolve** (`type: "thread"` only): Ask the user what to reply (or suggest a draft reply) and confirm the content. Queue the reply and resolve for Phase 4.
   - **Reply only** (`type: "thread"`): Ask the user what to reply (or suggest a draft reply) and confirm the content. Queue the reply for Phase 4.
   - **Comment only** (`type: "comment"`): Ask the user what to comment (or suggest a draft) and confirm the content. Queue the comment for Phase 4.
   - **Skip**: Do nothing, proceed to the next comment.
   - **Other (free-text)**: Follow the user's custom instructions for this comment. Code fixes are committed immediately; any GitHub API actions are queued for Phase 4.

4. After completing the action (or skipping), move to the next comment and repeat.

## Phase 4: Push & Execute Queued Actions

After all comments have been walked through:

1. **Show the triage summary**:

```
## Triage Summary

| # | Category | Author | Assessment | Action |
|---|----------|--------|------------|--------|
| 1 | <category> | @<author> | <assessment> | Fixed (committed) & reply & resolve (queued) / Fixed (committed) / Skipped / ... |
| 2 | ... | ... | ... | ... |

Pending GitHub actions: <n> replies, <n> comments, <n> resolves
```

2. **Ask: "Push?"** — If the user agrees, push to the remote. If the user declines, skip this step.

3. **Execute queued replies/comments/resolves** — Show the list of pending GitHub API actions. For actions that include a code fix, include the commit hash in the reply/comment (e.g., "Fixed in abc1234.").
   - **If push succeeded**: Ask "Execute queued replies/comments/resolves?" and execute if the user agrees.
   - **If push was declined**: Warn that executing replies/resolves before pushing means reviewers cannot see the fixes yet. Require explicit confirmation: "Execute queued replies/comments/resolves without pushing?" Only execute if the user confirms after this warning.
   - Endpoints:
     - For thread replies: `gh api` to `POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies`
     - For PR-level comments: `gh api` to `POST /repos/{owner}/{repo}/issues/{pull_number}/comments`
     - For thread resolves: `gh api graphql` using `thread_id` (not `comment_id`)
   - If the user declines, show the pending actions list so they can execute manually later.

4. **Show the final result**:

```
## Triage Complete

| # | Category | Author | Assessment | Action Taken |
|---|----------|--------|------------|--------------|
| 1 | <category> | @<author> | <assessment> | Fixed & replied & resolved / Fixed / Skipped / ... |
| 2 | ... | ... | ... | ... |

- Fixed: n
- Replied/Commented: n
- Resolved: n
- Skipped: n
```

## GitHub API Reference

- **Reply to an inline review comment (thread)**:
  `gh api repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies -f body="<reply>"`
- **Post a PR-level comment (issue comment)**:
  `gh api repos/{owner}/{repo}/issues/{pull_number}/comments -f body="<reply>"`
- **Resolve a review thread**:
  `gh api graphql -f query='mutation { resolveReviewThread(input: {threadId: "<thread_id>"}) { thread { id } } }'`

## Rules

- When the user selects a "Fix" action, this is an implicit request to commit. Draft a commit message, confirm it with the user, and commit. Do NOT push unless explicitly confirmed in Phase 4.
- When fixing code, make minimal changes that address the review comment.
- When suggesting reply drafts, keep them concise and professional.
- When drafting a PR-level comment for `type: "comment"`, always include a link to the original comment (`url` from JSON) at the beginning of the reply body (e.g., `> Re: <url>\n\n<reply body>`). PR-level comments have no threading, so without a link readers cannot tell which comment the reply addresses.
- If code context is unclear, search the codebase to verify before making a judgment.
- Prefer `gh` commands for GitHub data.