Pr

---
name: pr
description: Use when creating a pull request. Pushes the branch, creates the PR, and reports the URL.
argument-hint: "[additional context]"
allowed-tools:
  - Glob
  - Read
---

# Create Pull Request

**Autonomy:** model-invocable · pushes the branch and creates the PR autonomously · asks for missing input (base branch, template choice) and confirms before opening an empty PR

Pushes the branch and creates the pull request, then reports the URL.

## Arguments

```
$ARGUMENTS
```

Optional context to incorporate into the PR description - details not covered in commits, important considerations, areas needing attention, or anything to emphasize for reviewers.

## Instructions

### 1. Check for PR Template

Search for templates in order of precedence:

```
.github/pull_request_template.md
.github/PULL_REQUEST_TEMPLATE/*.md
pull_request_template.md
PULL_REQUEST_TEMPLATE/*.md
docs/pull_request_template.md
docs/PULL_REQUEST_TEMPLATE/*.md
```

If multiple templates exist in a `PULL_REQUEST_TEMPLATE/` directory, list them and ask which to use.

### 2. Gather Context

Run in parallel:
- `git status` - check for uncommitted changes
- `git log --oneline @{upstream}..HEAD 2>/dev/null || git log --oneline -10` - commits to include
- `git diff --stat @{upstream}..HEAD 2>/dev/null || git diff --stat HEAD~5..HEAD` - files changed

If there are staged changes ready to commit, ask whether to commit first or proceed.
If there are only untracked files (not relevant to the PR), proceed without asking.

### 3. Draft PR Content

**Title:** Derive from branch name or commits. Use conventional format if repo follows it. End with a mood emoji that reflects the vibe of the conversation or task.

Palette (use these or any GitHub emoji that fits):

| Emoji | Shortcode | Mood |
|-------|-----------|------|
| :sparkles: | `:sparkles:` | excited about something new |
| :tada: | `:tada:` | celebration, milestone |
| :fire: | `:fire:` | on a roll, crushing it |
| :bug: | `:bug:` | squashing something annoying |
| :face_with_spiral_eyes: | `:face_with_spiral_eyes:` | confused, dizzy, "what even is this" |
| :rage: | `:rage:` | frustrated, fighting the tools |
| :relieved: | `:relieved:` | finally fixed, weight off shoulders |
| :broom: | `:broom:` | tidying up, chores |
| :thinking: | `:thinking:` | exploratory, not sure yet |
| :coffin: | `:coffin:` | killing dead code, removing things |
| :rocket: | `:rocket:` | shipping, deploying, launching |
| :nail_care: | `:nail_care:` | polish, aesthetics, making it pretty |

**Body:** If template found, fill it in. Otherwise use:

```markdown
## Why

[Problem/motivation - 1-3 sentences]

## How

[How the work was built - skills/agents used, course-corrections.
See "Writing the How section" below.]

## What

[Approach - brief, not a code walkthrough]

## Notes for reviewers

[Non-obvious decisions, areas of uncertainty, or "looks wrong but isn't" explanations]

<!-- claude-session: ${CLAUDE_SESSION_ID} -->
```

Always append the `<!-- claude-session: ${CLAUDE_SESSION_ID} -->` line as the last line of the body — including when a PR template is used instead of the default body. `${CLAUDE_SESSION_ID}` is a Claude Code runtime substitution (resolved when this skill is invoked, not a chezmoi template value) and GitHub renders HTML comments invisibly, so it won't clutter the PR description. It records which session produced the PR, so the transcript stays reachable later — `cq -s <id>` scopes any query to that session.

If user provided additional context in arguments, incorporate it appropriately into the PR body.

Draft the content but don't show it to the user for approval - proceed directly to creation.

#### Writing the How section

The **How** section reconstructs the *process* used to build the work — the skill stack, agent usage, where reviews caught issues, how the plan adapted. It is most valuable when:

- The work spanned multiple skills or agents (e.g., orchestrated with `/work-on`)
- Course-corrections during the work shaped the final design
- The reviewer would benefit from understanding *why* the commits look the way they do

For a small bug fix or single-commit change, omit the section — there's nothing to say beyond the diff.

Reconstruct the workflow from the conversation: which skills ran, in what order, what each one contributed, where things diverged from the plan. Keep it factual and tight — a tree diagram is plenty. Avoid editorializing about which patterns "mattered" or which decisions were "good"; let the reader judge.

Example (from a Medium-tier feature orchestrated with `/work-on`):

```markdown
## How

Orchestrated end-to-end with `/work-on`, which composed Claude Code skills based on issue tier:

​```
/work-on
├── /checkout + /commit          ─ branch + ship unrelated fix separately
├── /gather-context              ─ 2 parallel Explore agents: codebase + API docs
├── /think                       ─ pressure-test design decisions, lock choices
├── /plan + /review-plan         ─ phased task graph; reviewer agent caught 3 blockers
├── /share-plan #N               ─ post design as collapsible comment on the issue
├── implement + /commit (×N)     ─ logical commits, each scoped to one concern
├── /simplify                    ─ 3 parallel reviewer agents (reuse / quality / efficiency)
└── /pr                          ─ open PR
​```

Course-corrections during the work: `/review-plan` flagged the download-protocol framing as ambiguous; `/simplify` caught path traversal in one of two call sites and a parameter-sprawl issue in the REST client signature.
```

Replace the example specifics with the actual flow — don't paste the example literally. The shape (tree diagram + a short note on course-corrections) is the reusable part.

### 4. Push and Create PR

**Push first:** If the branch hasn't been pushed or is behind:
```bash
git push -u origin <branch-name>
```

**Write the body to a temp file** (avoids shell escaping issues with backticks and code fences):
```bash
cat > /tmp/pr-body.md << 'PRBODY'
...formatted body...
PRBODY
```

**Then create the PR:**
```bash
gh pr create --title "..." --body-file /tmp/pr-body.md
```

### 5. Report Result

Report the PR URL returned by `gh pr create`.

## Examples

```
/pr                                           → Standard PR, reports the URL
/pr This needs careful review of the DB migrations → Emphasizes DB migration review
/pr The API changes are breaking but documented    → Highlights breaking changes
```

## Edge Cases

- **No upstream:** Ask for base branch
- **Empty diff:** Warn and confirm before creating empty PR
- **Draft PR:** If user mentions "draft" or "WIP", add `--draft` flag
- **Multiple templates:** List options, ask which to use