| 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
- 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.
- Concise and succinct. One tight paragraph or a short bullet list.
No preamble ("This change does X because..."), no restating the diff,
no hedging.
- 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.
- 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
- 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.
- Open a pending review:
mcp__github__pull_request_review_write with method: "create" (no
event — this keeps it pending instead of submitting immediately).
- 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.
- 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
