Pull Request Writer skill for Claude Code

A good PR lets a reviewer understand why it exists, where to look first, and how you know it works, in under two minutes of reading. The description is written for the reviewer today and for the engineer running git blame in two years.

Ground rules

• Read the actual diff before writing. Never describe the PR from the branch name or the commit subjects alone.
• Describe intent and reasoning; do not narrate the diff file by file.
• State what was tested and how, with real commands and results. Never claim tests pass without running them.
• Call out risk honestly. “Low risk” needs a reason.
• Follow the repo’s .github/pull_request_template.md (or docs/ variant) if present; fill every section instead of deleting the ones that feel tedious.

Workflow

- [ ] 1. Gather the diff, commits, linked issue, and template
- [ ] 2. Check size; split or stack if too large
- [ ] 3. Run the checks you will cite
- [ ] 4. Write the title
- [ ] 5. Write the description from the template below
- [ ] 6. Create or update the PR; self-review the rendered diff

1. Gather

git fetch origin
git log --oneline origin/main..HEAD
git diff --stat origin/main...HEAD          # three dots: changes since merge-base
git diff origin/main...HEAD                 # read it
ls .github/pull_request_template.md .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null
gh issue view <n>                           # if an issue is linked

2. Size check

Review quality drops sharply past a few hundred changed lines. Thresholds to apply, counting hand-written lines (exclude lockfiles, generated code, snapshots):

Changed lines	Action
< 200	Ideal; one PR
200–400	Fine if single-purpose; add a review path
400–1000	Split unless it is one indivisible change; justify in the description
> 1000	Split or stack; mechanical changes (renames, codemods) go in their own PR

Split along these seams, in order: mechanical refactor/rename -> new code behind a flag or unused -> wiring that turns it on -> cleanup of the old path. Each PR must build and pass on its own.

Stacked PRs (each branch based on the previous):

git switch -c feat/part-1 origin/main     # ...commit...
git switch -c feat/part-2                  # based on part-1
gh pr create --base main --head feat/part-1 --title "..." --body-file pr1.md
gh pr create --base feat/part-1 --head feat/part-2 --title "..." --body-file pr2.md
# after editing part-1, restack all dependent branches in one go:
git switch feat/part-2 && git rebase --update-refs origin/main

--update-refs (git 2.38+) moves intermediate branch pointers during the rebase. Say “Stacked on #123” at the top of each dependent PR. Tools like Graphite or git-town automate this; use them if the repo already does.

3. Run checks

Run the same commands CI runs (read .github/workflows/*.yml): tests, lint, type check, build. Capture counts or short output for the testing section.

4. Title

• If the repo squash-merges, the title becomes the commit subject on main: use the commit convention (feat(billing): support annual plans).
• Imperative, specific, under ~70 chars. Include the ticket ID if the repo does.
• Bad: “Fixes”, “Updates”, “PR for JIRA-123”, “WIP”.

5. Description template

## Why
<The problem or goal in 1–3 sentences. Link the issue: Closes #123.>

## What changed
- <Behavioral change 1, in user or system terms>
- <Behavioral change 2>
- <Notable non-change: "API shape unchanged; only the query moved">

## How to review
<Suggested order. "Start with `src/billing/plan.ts` (the core logic), then the
migration. `generated/` and the lockfile can be skimmed.">

## Testing
- `npm test` — 412 passed (3 new: annual proration, downgrade mid-cycle, leap year)
- Manual: created an annual plan in staging, upgraded mid-cycle, invoice matched
  expected $83.33 proration.

## Screenshots
| Before | After |
|---|---|
| <img> | <img> |

## Risk and rollout
- Risk: <what could break, blast radius, who is affected>
- Rollout: <behind flag `annual_plans`, default off; enable for internal org first>
- Rollback: <revert PR; migration is additive, no down-migration needed>

## Out of scope / follow-ups
- <Deliberately deferred work, with issue links>

Drop “Screenshots” for non-UI changes and “Risk and rollout” only for trivial changes (docs, test-only). Never leave placeholder text in the final description.

6. Create or update

gh pr create --base main --title "feat(billing): support annual plans" \
  --body-file /tmp/pr.md --draft          # draft until CI is green
gh pr edit 123 --body-file /tmp/pr.md     # update an existing PR
gh pr ready 123                            # leave draft
gh pr view 123 --web                       # check the rendered description
gh pr checks 123

Then self-review the diff in the PR UI: leave comments on lines that need context (“This looks unused but is called via reflection in X”), which saves a review round.

What to include by change type

Change type	Must include
UI	Before/after screenshots or a short recording; viewport sizes; dark mode if supported; accessibility checks done
API	Request/response example; backward compatibility statement; client impact
Database migration	Lock/duration expectations on production-size tables; backfill plan; rollback
Performance	Benchmark method and numbers before/after, same machine and dataset
Bug fix	Root cause in one or two sentences; the regression test name
Dependency upgrade	Version range, changelog highlights that matter, breaking changes handled
Security fix	Minimal public detail if the repo is public; coordinate disclosure first
Config / infra	Environments affected, order of applying, how to verify after deploy

Reviewer guidance

• Request reviewers who own the touched code (CODEOWNERS) plus one person for the risky part, not the whole team.
• Ask specific questions: “Is retrying here safe given the webhook is not idempotent?” beats “thoughts?”.
• Mark nits you would accept either way so reviewers do not block on them.
• When responding to review: reply to every thread, push fixes as new commits during review (so reviewers can see the delta), and resolve threads only after the reviewer’s concern is addressed.

Gotchas

• git diff origin/main..HEAD (two dots) includes changes on main you do not have; use three dots for “what this PR changes”.
• Stale base: rebase or merge main before asking for review if the PR is behind by conflicting changes; reviewers should not review conflict resolutions twice.
• Closes #123 only auto-closes when the PR merges into the default branch; for stacked PRs into another branch it does nothing.
• Screenshots with real customer data or tokens leak through PRs; crop or use seed data.
• Long descriptions get skipped. If it exceeds a screen, move detail into a linked design doc and keep the summary.
• Mixed-purpose PRs (“also fixed a typo in billing and bumped eslint”) slow review and complicate reverts; move extras to their own PR.

Verification

• The description answers: why, what changed, where to start, how it was tested, what could go wrong, how to undo it.
• Every claim in Testing corresponds to a command you actually ran in this session or CI output you read.
• gh pr view <n> shows the rendered body with no template placeholders.
• Size is within the thresholds above, or the description justifies why not.