Pr

---
name: pr
description: Create or update a GitHub Pull Request from the current branch. Reads all commits since the base branch, auto-generates a structured PR title and body (Summary / Changes / Test Plan sections), infers labels from commit types, and shows everything for approval before running gh pr create. Handles push if needed and detects existing PRs. Global and project-agnostic. Trigger when the user says "create a PR", "open a pull request", "make a PR", "/pr", "submit PR", or "push and open a PR".
---

# GitHub Pull Request — creation skill

Creates (or updates) a GitHub PR from the current branch using `gh pr create`.
Reads the full commit range, generates a structured body, and always shows the
complete proposal for user approval before touching GitHub. Never creates a PR silently.

## Accepted flags (parsed from the user's invocation text)

| Flag | Effect |
|---|---|
| `--draft` | Open as a draft PR instead of ready for review |
| `--base <branch>` | Override the target base branch (default: repo default branch) |
| `--reviewer @handle` | Assign one or more reviewers (repeat for multiple) |
| `--label <name>` | Add a label in addition to any auto-inferred ones |
| `--closes <N>` | Append `Closes #N` to the PR body |
| `--refs <N>` | Append `Refs #N` to the PR body |
| `--web` | Open the PR in the browser after creation |
| `--british` | British English spelling in title and body (default: American English) |

If the user provides a free-text hint (e.g. `/pr fix the auth regression`), use it as
a strong signal for the title and Summary — do not ignore it.

## Procedure

### 1. Parse flags and hint
Extract all flags above and any free-text hint from the user's invocation.

### 2. Gather context (run in parallel)
- `git rev-parse --abbrev-ref HEAD` — current branch name.
- `gh repo view --json defaultBranchRef -q .defaultBranchRef.name` — repo default branch.
- `git log <base>...HEAD --oneline` — all commits included in this PR.
- `git diff <base>...HEAD --stat` — files and line counts changed.
- `git diff <base>...HEAD --name-only` — file list for scope/label inference.
- `gh pr list --head <branch> --json number,url,title` — detect any existing PR for this branch.
- Check for `.github/pull_request_template.md` — use it as the body structure if present.

Where `<base>` is the `--base` flag value, or the repo default branch if not specified.

### 3. Existing PR guard
- If a PR already exists for this branch: show its number, title, and URL.
- Ask the user whether to **edit the existing PR** (`gh pr edit`) or abort.
- If editing: skip steps 4–8 and go straight to proposing updated title/body, then run
  `gh pr edit <number> --title "..." --body "..."`.

### 4. Branch guard
- If the current branch is the same as the base branch (e.g. opening a PR from `main` to
  `main`): warn and ask for confirmation before proceeding.

### 5. Push check
- Run `git rev-parse --abbrev-ref @{u}` to detect whether the branch has a remote upstream.
- If no upstream: state that a push is required for GitHub to accept the PR.
  Ask for confirmation, then run `git push -u origin <branch>`.
- If upstream exists but the local branch is ahead: run `git push` (standard, non-force).

### 6. Infer labels from commit types
Map the commit types present in the range to GitHub label names:

| Commit type | Suggested label |
|---|---|
| `feat` | `enhancement` |
| `fix` | `bug` |
| `docs` | `documentation` |
| `chore` / `ci` / `build` | *(no label)* |
| `perf` | `performance` |
| `refactor` | `refactor` |
| `test` | `testing` |
| `--breaking` flag or `!` in any commit | `breaking change` |

Combine with any `--label` flags from the user. Propose the full label list and let the
user accept, change, or drop any.

### 7. Compose the PR title
- Single commit in range → derive title directly from that commit's subject line.
- Multiple commits → synthesize a concise subject that captures the overall change.
- Follow Conventional Commits format for the title: `<type>(<scope>): <description>`.
- ≤72 characters. Imperative mood, lowercase after the colon.
- Apply `--british` if flagged.

### 8. Compose the PR body

If `.github/pull_request_template.md` exists, fill its sections rather than using the
default structure below.

Otherwise use these fixed sections:

```text
## Summary
<bullet points: what changed and why — the motivation, not the mechanics>

## Changes
<bullet list of files/modules touched with a one-line description each>

## Test plan
<markdown checklist: concrete steps to verify the change works and hasn't broken anything>
```

Append at the bottom:
- `Closes #N` / `Refs #N` footers if `--closes` or `--refs` were passed.
- A `🤖 Generated with [Claude Code](https://claude.ai/claude-code)` attribution line
  (standard for AI-assisted PRs; omit only if the user explicitly asks).

Draw content from the full commit range (`git log`) and diff stat — summarize ALL commits,
not just the most recent.

### 9. Show the full proposal and wait for approval
Present in one block:
- **Title**
- **Base branch** → **Head branch**
- **Draft**: yes / no
- **Labels**: list
- **Reviewers**: list (or none)
- **Body**: full text

Ask the user to approve, edit specific sections, or cancel. Do not proceed until approved.

### 10. Create the PR
Build the `gh pr create` command from the approved proposal:

```bash
gh pr create \
  --title "<title>" \
  --body "$(cat <<'EOF'
<body>
EOF
)" \
  [--base <branch>] \
  [--draft] \
  [--reviewer <handle>] \
  [--label <name>] \
  [--web]
```

If label names don't exist in the repo yet, `gh` will error — catch this and offer to
create the missing labels or skip them.

### 11. Report
- Print the PR URL.
- If `--web` was passed, confirm the browser was opened.
- If push was required (step 5), confirm the remote branch is now set.

## Guardrails
- **Never create or edit a PR without user approval** of the full title + body proposal.
- **Never force-push** — only `git push` or `git push -u origin <branch>`.
- **Detect existing PRs** before creating; never open a duplicate silently.
- **Warn before pushing** if the branch has no upstream; require confirmation.
- **Summarize ALL commits** in the range, not just the latest one.
- Keep the title ≤72 characters.
- If `gh` is not authenticated or not installed, say so clearly and stop.
- Never invent file names, commit messages, or issue numbers — derive everything from
  actual `git` and `gh` output.
- If the repo has no default branch detectable via `gh`, fall back to asking the user.