pr-create

PR create

Compose before opening. The body is the squash-merge commit context — write it for the reviewer first, the future reader of git log second.

Pre-flight

# REST reads — see ~/.claude/CLAUDE.md "GitHub API budget".
branch=$(git branch --show-current)
gh api repos/:owner/:repo/pulls \
  --jq ".[] | select(.head.ref==\"$branch\") | {number, state, url}"  # existing PR for this branch?
git log --oneline main..HEAD          # what this PR actually contains
gh api repos/:owner/:repo/pulls/<N> --jq '.body'   # iterating? read the current body

• Existing PR for the branch → iterate on it, don't open a second.
• Find the issue this resolves (branch name, commit trailers, the task). A PR that closes one carries Closes #<N> in the body.

Detect repo template

ls .github/pull_request_template.md \
   .github/PULL_REQUEST_TEMPLATE.md \
   .github/PULL_REQUEST_TEMPLATE/ \
   docs/pull_request_template.md 2>/dev/null

Template present → fill its sections; don't swap its structure for ours. Absent → use the structure below.

Body structure (no template)

Three short blocks. A reviewer should grasp all three in one read; a block that runs past a few lines is carrying detail the diff already shows.

• Summary — why this change. Prose, 1-2 sentences leading with the user-visible outcome ("X now works"), not the diff ("set Y to Z"). Surface mechanism only when the choice isn't obvious. Link the issue; don't re-explain it. Bad: "Set format_space \"#[bg=16]\" in pair.kdl." Good: "Bar paints uniformly black across the format gap, closing the lighter strip from #68."
• Gotchas — what'll surprise the reviewer. A bullet per pointer: where to spend attention and why, not an exhaustive risk dump. Typical: off-diff state (a label/secret/setting changed remotely), a silent-failure mode, a non-obvious constraint, something that reads like a typo. Litmus: a gotcha completes "watch out — ___", not "I chose ___ because ___"; rationale goes to Summary or gets cut. Omit when nothing surprises. Bad: "Split into two workflows so each trigger is self-documenting." Good: "Labeling pins .../autolabeler@<sha>, a subpath of the same action — not a typo."
• Verification — how we know it's correct. A bullet per material check beyond CI, past tense ("ran X, confirmed Y"). Skip trivial steps. Omit the section when CI covers everything; unverified items go in Gotchas, not here.