cmd-pr-gh-comments

What this skill does

# Tend to GitHub PR Comments <!-- omit in toc -->

Pull all review comments from the current branch's PR, study their surrounding context, hunt for adjacent improvements, build a holistic plan, align with the developer, then execute.

- [1. Prerequisites](#1-prerequisites)
- [2. Identify the PR](#2-identify-the-pr)
- [3. Pull All Comments (with Line Ranges)](#3-pull-all-comments-with-line-ranges)
- [4. Gather Surrounding Context](#4-gather-surrounding-context)
- [5. Hunt for Adjacent Improvements](#5-hunt-for-adjacent-improvements)
- [6. Build the Holistic Plan](#6-build-the-holistic-plan)
- [7. Execute the Plan](#7-execute-the-plan)
- [8. Ask to Resolve Threads](#8-ask-to-resolve-threads)
- [9. Ask to Refine AGENTS.md Style](#9-ask-to-refine-agentsmd-style)
- [10. Ask to Update cmd-olshanskify Code Template](#10-ask-to-update-cmd-olshanskify-code-template)
- [11. Wrap Up](#11-wrap-up)

## 1. Prerequisites

Verify the environment is ready.

**Check authentication:**

```bash
gh auth status
```

If not authenticated, stop and tell the user to run `gh auth login`.

**Check current branch:**

```bash
git branch --show-current
```

Confirm you are not on the default branch. If you are, stop and ask the user to check out their feature branch.

## 2. Identify the PR

**Get PR details:**

```bash
gh pr view --json number,url,headRefName,baseRefName
```

If no PR exists for the current branch, stop and tell the user.

**Get repo owner/name:**

```bash
gh repo view --json nameWithOwner -q '.nameWithOwner'
```

Parse this into `{owner}` and `{repo}` for API calls below.

## 3. Pull All Comments (with Line Ranges)

Fetch every comment type and capture the full location span for each one.

**Inline review comments:**

```bash
gh api repos/{owner}/{repo}/pulls/{pr_number}/comments --paginate
```

**Review-level comments:**

```bash
gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews --paginate
```

**General PR conversation comments:**

```bash
gh api repos/{owner}/{repo}/issues/{pr_number}/comments --paginate
```

**Get current user for filtering:**

```bash
gh api user -q '.login'
```

For each inline comment, extract:

- `id`, `node_id`, `user.login`, `body`, `created_at`, `in_reply_to_id`
- `path`
- `start_line` (nullable — present for multi-line comments)
- `line` (the end line of the comment anchor)
- `original_start_line`, `original_line` (fallbacks if the comment is outdated)
- `start_side`, `side` (`LEFT` = base, `RIGHT` = head)
- `diff_hunk`
- `position` (null → comment is outdated)

Normalize every comment into `{file, start_line, end_line, side}` — if `start_line` is null, use `line` for both. This span is the **context window** used in the next step.

**Filter out:**

- Bot comments (`user.type == "Bot"`)
- Already-resolved threads

**Note:** Do NOT filter out comments authored by the current user. Users often leave self-review notes as action items.

**Group** inline review comments into threads by `in_reply_to_id`. The latest comment in a thread determines the thread's status.

If zero comments remain after filtering, report "No open PR comments to address" and stop.

## 4. Gather Surrounding Context

For each comment, read beyond the exact line range so the plan accounts for nearby intent, not just the flagged snippet.

For each `{file, start_line, end_line}`:

1. **Read a widened window.** Read the file with roughly 30 lines of padding on each side of the comment span. This captures the enclosing function, struct, or block.
2. **Scan for signals** inside that window and record them alongside the comment:
   - `TODO`, `TODO_*`, `FIXME`, `HACK`, `NOTE`, `XXX` markers
   - Docstrings / godocs / JSDoc immediately above the enclosing symbol
   - Inline comments explaining intent, invariants, or workarounds
   - Deprecation markers, feature flags, or version gates
   - Recently touched siblings in the same file (use `git blame -L start,end <file>` if the reviewer's concern might be historical)
3. **Locate the enclosing symbol.** Identify the function/method/class/struct that owns the commented lines — the plan should reason at that granularity, not just the flagged expression.
4. **Note cross-references.** If the comment references another symbol (e.g. "this duplicates `FooBar`"), mark it as a lookup target for the next step.

Record the gathered context as a compact note per comment — it feeds both the plan and the adjacent-improvement hunt.

## 5. Hunt for Adjacent Improvements

Look outside the PR diff for related code that would benefit from the same fix, using `rg` (ripgrep) and any signals from the user or from step 4.

For each comment, especially those classified as systemic (naming, pattern, anti-pattern, missing validation, etc.):

**Search for duplicates / siblings of the flagged pattern:**

```bash
rg "<pattern or symbol from the comment>" -n --hidden
```

**Search for related TODOs that would be closed by the same fix:**

```bash
rg "TODO|FIXME|HACK" -n <relevant_dir>
```

**Search for callers of the enclosing symbol** to see whether a fix ripples:

```bash
rg "\b<symbol>\b" -n -t <language>
```

**Ask the user** when signal is ambiguous:

> I see the reviewer flagged `<X>` at `<file>:<lines>`. Before planning, is there a broader pattern you'd like me to sweep for (e.g. other call sites, similar abstractions, sibling modules)? Or any area you explicitly want me to leave alone?

Collect each finding as an **adjacent improvement candidate** tagged with the originating comment. These do not become mandatory fixes — they become proposals in the plan that the user can accept, defer, or reject.

## 6. Build the Holistic Plan

Now classify every comment and merge in the adjacent improvements so the plan is one coherent pass, not a comment-by-comment checklist.

| Category | Description | Example |
|---|---|---|
| **Fix** | Clear, actionable code change requested | "This should use `===` not `==`" |
| **Investigate** | Needs codebase exploration before deciding | "Is this duplicated anywhere else?" |
| **Discuss** | Design question, trade-off, or needs clarification | "Should we use strategy A or B here?" |
| **Acknowledge** | FYI or praise, no action needed | "Nice refactor" |
| **Outdated** | Comment on code that has already changed | `position` is null or diff hunk no longer matches |

**Rules:**

- For **Fix** items, cite the real current file contents (not the diff hunk) when proposing a change.
- Group related comments that share a root cause into a single plan item.
- Surface **adjacent improvements** from step 5 as their own numbered proposals under each originating comment, each flagged `[adjacent]` and marked opt-in.
- Do not execute anything yet.

**Present the plan** to the user in this format:

```markdown
## PR Comment Triage: {pr_url}

### Fix ({count})
- [ ] **{file}:{start_line}-{end_line}** — {summary of what to change}
  > {abbreviated reviewer comment}
  - Context: {enclosing symbol, TODO/NOTE hits, relevant docstring}
  - [adjacent, opt-in] {related site at other_file:lines} — {why it may want the same fix}

### Investigate ({count})
- [ ] **{file}:{start_line}-{end_line}** — {what to explore and why}
  > {abbreviated reviewer comment}

### Discuss ({count})
- [ ] **{file}:{start_line}-{end_line}** — {question or design decision}
  > {abbreviated reviewer comment}

### Acknowledge ({count})
- {comment summary} — propose resolving, no action needed

### Outdated ({count})
- {comment summary} — code has changed, propose resolving

### Adjacent Improvements (opt-in)
- [ ] {file:lines} — {summary, tied back to originating comment}
```

Then ask:

> Here is the holistic plan for this PR's comments plus adjacent improvements I noticed. Do you want to:
> 1. Proceed as-is
> 2. Reclassify any items (e.g. move a Fix to Discuss)
> 3. Skip specific items or adjacent improvements
> 4. Add anything I missed
>
> Let me know before I start making changes.

**Do not proceed until the user confirms.**

## 7. Execute the Plan

Work through