resolve-pr-issues

What this skill does

# PR Issue Resolver

Orchestrate resolution of all outstanding PR feedback — inline comments, review bodies, and CI failures — through a structured triage-then-dispatch pipeline.

## When to Activate

- User mentions PR review comments to address
- CI/CD checks are failing on a PR
- User wants to fix a pull request
- User needs to respond to reviewer feedback
- Build or tests failing on a PR
- User says "fix my PR" or "address the comments"

## Workflow Overview

```text
Phase 0: Input Parsing
    ↓
Phase 1: Gather (parallel fetch)
    ↓
Phase 2: Normalize (unified item list)
    ↓
Phase 3: Triage (act vs. explain-why-not)
    ↓
Phase 4: Dispatch (subagents for code changes, direct replies for explanations)
    ↓
Phase 5: Collect & Verify
    ↓
Phase 6: Commit & Report
```

---

## Phase 0: Input Parsing

Extract from the user's request:

- **`pr_number`** (required): Parse from user message, PR URL, or prompt for it
- **`owner`** (optional): Infer via `gh repo view --json owner --jq '.owner.login'`
- **`repo`** (optional): Infer via `gh repo view --json name --jq '.name'`

**Validate access and state** before proceeding:

```bash
gh pr view {pr_number} --json number,title,state --jq '{number, state}'
```

- If the command fails (access error, PR not found), surface the error to the user. Do not continue.
- If `state` is `MERGED` or `CLOSED`, warn the user: "PR #{number} is {state}. Do you still want to proceed?" Require explicit confirmation before continuing — resolving comments on a merged/closed PR is almost never what the user intended.

## Phase 1: Gather

Fetch all PR data in parallel:

| Data            | Primary Method                                       | Fallback                                              |
| --------------- | ---------------------------------------------------- | ----------------------------------------------------- |
| PR details      | `pull_request_read(method: "get")`                   | `gh pr view {number} --json title,author,state,body`  |
| Inline comments | `pull_request_read(method: "get_review_comments")`   | `gh api repos/{owner}/{repo}/pulls/{number}/comments` |
| Review bodies   | `gh api repos/{owner}/{repo}/pulls/{number}/reviews` | None (primary method — MCP lacks reviews endpoint)    |
| CI status       | `pull_request_read(method: "get_status")`            | `gh pr checks {number}`                               |
| PR diff         | `pull_request_read(method: "get_diff")`              | `gh pr diff {number}`                                 |
| Changed files   | `pull_request_read(method: "get_files")`             | `gh pr view {number} --json files`                    |

> **Note**: The changed files list is used in Phase 4 to scope agent work — agents should only modify files in this list (plus cross-file references). It also helps validate that inline comment file paths actually exist in the PR diff.

### Error Handling

- **Inline comments**: If both `pull_request_read` MCP and `gh api` fallback fail for inline comments, **stop and surface the error immediately**. Inline comments are the primary input — do not proceed with an empty comment list. The user must resolve the access issue before the workflow can continue.
- **Review bodies**: If `gh api` for review bodies fails (auth, rate limit, network), **surface the error to the user** before proceeding. The workflow may continue with inline comments and CI items, but the user must know review bodies were not fetched. Do not silently skip them.
- **CI status / diff / changed files**: If these fail, surface the error but allow the workflow to continue with reduced functionality. Note the missing data in the triage summary.

## Phase 2: Normalize

Parse all feedback into a **unified item list**. Each item has:

| Field          | Type                                  | Description                                             |
| -------------- | ------------------------------------- | ------------------------------------------------------- |
| `id`           | string                                | Comment ID or generated identifier                      |
| `source`       | `"inline"` / `"review_body"` / `"ci"` | Where the feedback came from                            |
| `author`       | string                                | GitHub username                                         |
| `is_bot`       | boolean                               | True for CI bots, GitHub Actions, etc.                  |
| `is_resolved`  | boolean                               | True if thread is resolved or comment is outdated       |
| `location`     | `{file, line}` or `null`              | Code location (null for review body items, CI failures) |
| `content`      | string                                | Comment text or CI failure description                  |
| `review_state` | string                                | APPROVED, CHANGES_REQUESTED, COMMENTED                  |
| `blocking`     | boolean                               | Derived from review state + language analysis           |
| `context`      | string                                | Surrounding code or CI log excerpt                      |

### Resolved/Outdated Detection

- Inline comments with `position: null` → outdated (diff line no longer exists)
- Comment threads marked as resolved → already handled
- Set `is_resolved: true` — these are filtered out during triage

### Blocking Classification

- `CHANGES_REQUESTED` review state → default `blocking: true`
- `COMMENTED` or `APPROVED` review state → default `blocking: false`
- Language overrides: "must", "required", "blocking", "critical", "security", "vulnerability" → `blocking: true`
- Language overrides: "nit", "optional", "consider", "suggestion", "minor", "nice to have" → `blocking: false`
- CI failures → always `blocking: true`

### Review Body Parsing

The review body is free-form text. Parse it into discrete items:

- Each bullet point, numbered item, or paragraph with a distinct concern = one item
- Standalone questions = separate item (will become RESPOND_ONLY)
- General praise/acknowledgment = skip (no item created)

### CI Bot Deduplication

If an inline comment author is a known bot (e.g., `github-actions[bot]`, `codecov-commenter`, `renovate[bot]`) AND the content overlaps with a CI check failure on the same file/line, merge into one item. Use the inline comment as the canonical item (it has location context).

**Exception**: Do NOT deduplicate when the inline bot comment is stale or resolved (`is_resolved: true`). In that case, keep the CI failure as a separate item — a stale bot comment does not mean the underlying CI failure is resolved.

## Phase 3: Triage

For each normalized item, classify:

| Classification    | Criteria                                                                  | Action                      |
| ----------------- | ------------------------------------------------------------------------- | --------------------------- |
| `ACTION_REQUIRED` | Specific code change suggested, bug reported, CI failure, lint/type error | Dispatch to subagent        |
| `RESPOND_ONLY`    | Question asked, concern raised without specific fix, design discussion    | Post reply with explanation |
| `NO_ACTION`       | Praise, acknowledgment, already resolved, outdated, duplicate             | Log in report               |

### Decision Tree

Apply in order — first match wins:

1. Is the thread already resolved or outdated? → `NO_ACTION`
2. Is it a CI failure? → `ACTION_REQUIRED`
3. Is it a bot comment with specific errors? → `ACTION_REQUIRED`
4. Does it suggest a specific code change? → `ACTION_REQUIRED`
5. Does it report a bug or incorrect behavior? → `ACTION_REQUIRED`
6. Does it raise a potential bug concern without a specific fix (e.g., "this looks wrong", "this seems buggy")? → `RESPOND_ONLY`, but **flag for user review** in the triage summary — the user may want to promote it to `ACTION_REQUIRED`
7. Does it ask a question or