Pr Annotate

---
name: pr-annotate
description: >-
  Leave inline GitHub review comments on a PR's changed files explaining why
  each change was made. Use automatically right after creating a pull
  request with mcp__github__create_pull_request (or the gh CLI), before
  telling the user the PR is up — do not wait to be asked. Also use when the
  user explicitly asks to annotate a PR's code changes or explain the "why"
  behind a diff.
---

# pr-annotate (inline rationale comments on a new PR)

## When this runs

Immediately after opening a PR. The PR body already says *what* changed;
these comments say *why* — the reasoning a reviewer can't get from the diff
alone (why this file was touched, why one duplicate was kept over another,
why a helper was promoted vs. left local).

Skip files where the "why" is already obvious from the change itself (a
one-line typo fix, a version bump) — annotate only where the rationale adds
information the diff doesn't already carry.

## Rules for every comment

1. **No attribution footer in the body you write.** Do not append
   `_Generated by [Claude Code](...)_` or any `---` divider to the comment
   text yourself. Known platform limitation: the GitHub integration
   server-appends this footer to every post regardless of body content —
   confirmed on inline review comments even when the footer was omitted
   from the call. There is currently no tool-level way to suppress it, so
   don't spend time working around it; just never add it yourself so
   nothing doubles up if that ever changes.
2. **Concise and succinct.** One tight paragraph or a short bullet list.
   No preamble ("This change does X because..."), no restating the diff,
   no hedging.
3. **2-3 bullet points max per comment.** If a file's rationale doesn't
   fit in 2-3 bullets, the file should probably be two comments (or the
   PR should probably be two PRs) — don't write a wall of text in one
   comment to avoid that.
4. **Link referenced functions/symbols** using GitHub permalinks
   (`https://github.com/<owner>/<repo>/blob/<commit-sha>/<path>#L<line>`
   or `#L<start>-L<end>` for a range) so the link expands to a code
   preview in GitHub's UI. Use the exact commit SHA the PR head is on
   (from `pull_request_read` `get_commits`, or the tool's own PR-create
   response), not a branch name — branch names drift as the PR gets more
   commits, breaking the anchor.

## Workflow

1. Get the diff and the head commit SHA:
   `mcp__github__pull_request_read` with `method: "get_files"` (for the
   patches) and `method: "get_commits"` (for the latest SHA), or read
   both off the `create_pull_request` response if freshly opened.
2. Open a pending review:
   `mcp__github__pull_request_review_write` with `method: "create"` (no
   `event` — this keeps it pending instead of submitting immediately).
3. For each file worth annotating, call
   `mcp__github__add_comment_to_pending_review` with `subjectType: "FILE"`
   (file-level, since the rationale usually spans the whole file's diff,
   not one line) and a body following the rules above — a permalink or
   two to the specific function(s) the comment is about, and 2-3 bullets
   of reasoning.
4. Submit once: `mcp__github__pull_request_review_write` with
   `method: "submit_pending"`, `event: "COMMENT"`, and a short top-level
   body. The top-level submit body follows the repo's normal GitHub-post
   convention and *does* get the attribution footer — only the per-file
   inline comments added in step 3 omit it.

## Example comment body

```
Promoted to `TestRepo` in [`e2e_test_helpers.rs`](https://github.com/treq-dev/treq/blob/10f9fa7/src-tauri/tests/e2e_test_helpers.rs#L89-L96) since 4 other test files had byte-identical copies.

- Removed the local duplicate here
- Kept `assert_working_copy_clean` local — not duplicated elsewhere
```