pr

Create a GitHub pull request from the current branch.

Most of this command is mechanical (gh commands, signal detection). The part that matters is how you write the PR description — that's where this command actually thinks. Read the Voice section first; it's the rubric for Step 6.

Voice

Write like you're explaining the PR to a coworker on Slack. Not "I changed auth.py and updated utils.py" — "I added token expiry checks so logged-out sessions stop working."

Bad — exactly what to avoid:

• Replace the search_cache round-trip with direct lookups against products and listings
• Rename build_search_query to fetch_product_ids
• Use parameterized queries instead of f-string interpolation

Good — same diff:

• Product search no longer depends on the search cache (being retired) and reads from the product tables directly
• Delisted products are now left out of search results — previously they could still show up
• Fixed a SQL injection risk where store_id and category ids were interpolated into query strings

Every bullet answers either what does this change do for the system? or why was it needed? — never describes code mechanics. No file or function names. Housekeeping (renames, formatting, import cleanup) folds into another bullet or gets omitted.

Step 0 — Parse $ARGUMENTS

All optional, never prompt for them:

• --base <branch> — override base
• --draft — create as draft
• --reviewer <handle> — repeatable
• --milestone <name>

Step 1 — Pre-flight

gh auth status
git rev-parse --show-toplevel
BRANCH=$(git branch --show-current)
DEFAULT=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')
BASE=${ARG_BASE:-$DEFAULT}

Abort with a specific message if:

• on $DEFAULT → "You are on $DEFAULT — create a feature branch first."
• git log origin/$BASE..HEAD --oneline is empty → "No commits ahead of $BASE. Nothing to PR."

Check for an existing PR:

gh pr list --head "$BRANCH" --json number,url

If one exists, show the URL and ask: "PR already exists. (open / abort)"

Step 2 — Gather context

# Commit messages — primary source for intent
git log origin/$BASE..HEAD --format="%s%n%b---%n"

# Size and shape (filtered)
EXCLUDES="-- :!*.lock :!package-lock.json :!yarn.lock :!poetry.lock \
  :!*.snap :!dist/* :!build/* :!*.generated.* :!*_pb2.py \
  :!*.min.js :!*.min.css"

git diff origin/$BASE...HEAD --stat $EXCLUDES
git diff origin/$BASE...HEAD $EXCLUDES

If the filtered diff is over ~600 lines, read --stat plus only the core logic files. Skip fixtures, assets, generated code.

Signal detection — one pass over the changed-files list:

git diff origin/$BASE...HEAD --name-only

From that list, note presence of:

• env vars: *.env.example lines added
• migrations/schema: migration|schema|\.sql
• new services: docker-compose|k8s/|\.service
• public docs/API: readme|docs/|openapi|swagger
• security-sensitive: auth|password|secret|token|crypto|permission|rbac|oauth|jwt|credential → set SECURITY_FLAG

Size flag: if insertions + deletions from the filtered stat > 800 → set SIZE_WARNING.

Ticket refs: grep [A-Z]+-[0-9]+ from $BRANCH and from commit messages.

Step 3 — Labels and CODEOWNERS

gh label list --limit 100 --json name,description
cat .github/CODEOWNERS 2>/dev/null || cat CODEOWNERS 2>/dev/null

Pick 1–3 labels that exist in the repo — never invent. Cross-reference changed paths against CODEOWNERS for reviewer suggestions, but only if --reviewer wasn't passed.

Step 4 — Push

git push -u origin "$BRANCH"

If this fails, surface the exact error and stop. Never force-push.

Step 5 — Title

Sentence case, ≤72 chars, no emoji. Append the ticket ref if one was found.

Example: Leave delisted products out of search results (SHOP-123)

Step 6 — Body

Use this template. Strip all HTML comments and placeholder text from the final output.

## Change Overview
<CHANGE_OVERVIEW>

### Change Checklist
- [x] I have performed a self-review of my code
- [x] I have added necessary tags for the PR
<CONDITIONAL_ITEMS>
- [ ] I have included related PR's in order of dependency.
  - include here
- [ ] This is a release PR and have posted to #releases channel about this
  - slack thread link

### Testing Overview
- [ ] I have added proof of thorough testing
  - include proof here

### Instructions for the reviewer
<REVIEWER_INSTRUCTIONS>

Change Overview: 2–5 bullets, fewer is better. Group ruthlessly. Lead with the highest-impact change. Follow the Voice section at the top — that is the rubric. Commit messages are the primary source for intent; the diff is secondary.

If SIZE_WARNING is set, add a final bullet noting the size and suggesting git log origin/$BASE..HEAD for commit-by-commit review.

Conditional checklist items — include only the ones matching signals from Step 2; delete the rest entirely (don't leave them unchecked):

Reviewer instructions: what to exercise, one happy path + one edge case, expected outcome, any setup. For pure refactors or PRs under ~100 lines, collapse to one line: "Pure refactor — verify <existing suite / specific regression> still passes."

If SECURITY_FLAG is set, add: "Touches security-sensitive code (<area>). Verify <specific invariant> still holds and check for unintended access-control changes."

Step 7 — Confirm

Print the full composed PR:

========================================
TITLE:     <title>
BASE:      <base>
LABELS:    <labels>
DRAFT:     yes / no
REVIEWERS: <handles, or "none — CODEOWNERS will apply">

BODY:
<body>
========================================
Looks good? (y / edit / abort)

• y → Step 8
• edit → ask what to change, re-show, repeat until y
• abort → stop

Do not proceed without an explicit y.

Step 8 — Create

cat > /tmp/pr_body.md << 'PRBODY'
<confirmed body>
PRBODY

gh pr create \
  --title "<title>" \
  --body-file /tmp/pr_body.md \
  --base "$BASE" \
  --label "<label>" [--label "<label>"...] \
  [--draft] [--reviewer "<handle>"...] [--milestone "<name>"]

Print the PR URL after creation.