Opening a pull request

---
name: opening-a-pull-request
description: Use when opening a pull request or writing/editing a PR description (e.g. `gh pr create`, "open a PR", "draft a PR", updating an existing PR body).
---

# Opening a Pull Request

A PR description is written for a busy human reviewer. It explains **why** the change exists and gives just enough context to review it — not a transcript of how it was built.

## The body is, in order

1. **The repo's template, always.** Start from `.github/PULL_REQUEST_TEMPLATE.md` in the local repo. Fill every section that applies; leave inapplicable checklist items unchecked rather than deleting them. Never invent your own structure when a template exists.
2. **A reason for the change.** Lead with the problem or motivation — what was wrong, missing, or needed. A reviewer should understand the point before any detail.
3. **Relevant code history/context, where applicable.** Brief background on how the code got to this state or how it behaved before, when that motivates the change. Skip it when it adds nothing.
4. **`## Considerations` (only when warranted).** Add this section only when you chose between genuinely valid approaches. State the options and why this one. Omit it for changes with one obvious approach.

## Voice

- Brief and plain. Short sentences, bullets over paragraphs.
- For a human, not a machine. No restating the diff.
- Avoid referencing code (symbols, file paths, function names) unless a specific identifier is genuinely needed to make a point.

## Do not include

- A narrative of the work or the back-and-forth decisions made while coding — unless a specific decision is something the reviewer needs to know.
- Implementation detail that the diff already shows.

## Mechanics

- Always open the PR as a draft (gh pr create --draft). Never open it ready-for-review by default.
- Before editing an existing PR body, **fetch the current body first** and preserve manual edits — don't clobber them.
- Follow the repo's contribution conventions (issue-ID format, branch naming, what not to link/mention). Check `AGENTS.md`/`CONTRIBUTING.md` if unsure.

## Smell test before submitting

- Could a reviewer who never saw the session understand *why* in 10 seconds?
- Did I paste code or narrate steps the diff already shows? Cut it.
- Is every template section addressed?

---
name: opening-a-pull-request
description: Use when opening a pull request or writing/editing a PR description (e.g. `gh pr create`, "open a PR", "draft a PR", updating an existing PR body).
---

# Opening a Pull Request

A PR description is written for a busy human reviewer. It explains **why** the change exists and gives just enough context to review it — not a transcript of how it was built.

## The body is, in order

1. **The repo's template, always.** Start from `.github/PULL_REQUEST_TEMPLATE.md` in the local repo. Fill every section that applies; leave inapplicable checklist items unchecked rather than deleting them. Never invent your own structure when a template exists.
2. **A reason for the change.** Lead with the problem or motivation — what was wrong, missing, or needed. A reviewer should understand the point before any detail.
3. **Relevant code history/context, where applicable.** Brief background on how the code got to this state or how it behaved before, when that motivates the change. Skip it when it adds nothing.
4. **`## Considerations` (only when warranted).** Add this section only when you chose between genuinely valid approaches. State the options and why this one. Omit it for changes with one obvious approach.

## Voice

- Brief and plain. Short sentences, bullets over paragraphs.
- For a human, not a machine. No restating the diff.
- Avoid referencing code (symbols, file paths, function names) unless a specific identifier is genuinely needed to make a point.

## Do not include

- A narrative of the work or the back-and-forth decisions made while coding — unless a specific decision is something the reviewer needs to know.
- Implementation detail that the diff already shows.

## Mechanics

- Always open the PR as a draft (gh pr create --draft). Never open it ready-for-review by default.
- Before editing an existing PR body, **fetch the current body first** and preserve manual edits — don't clobber them.
- Follow the repo's contribution conventions (issue-ID format, branch naming, what not to link/mention). Check `AGENTS.md`/`CONTRIBUTING.md` if unsure.

## Smell test before submitting

- Could a reviewer who never saw the session understand *why* in 10 seconds?
- Did I paste code or narrate steps the diff already shows? Cut it.
- Is every template section addressed?