write-pull-requests git:20261009.a9dd4c0A

Immutable. This exact content never changes and is served at /api/v1/blob/f1134685280ad96b.

---
name: write-pull-requests
description: Use when opening or updating a pull request — produces a bug-fix or feature description reviewers from junior to CTO can follow end to end.
---

# Write Pull Requests

The description is the cheapest review tool the author controls: it decides whether the
reviewer follows the change or reverse-engineers it. Two fixed shapes, filled from the
diff and from output that actually scrolled by — never from memory of what you meant to
build.

## 1. Audit — what does the branch ship, and does a PR exist?

```bash
git log main..HEAD --oneline          # substitute the repo's default branch
git diff main --stat                  # or: git show <sha>, for a PR shipping one existing commit
ls .github/PULL_REQUEST_TEMPLATE.md .github/pull_request_template.md \
   .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null
gh pr view --json number,title,body 2>/dev/null
```

Change nothing yet. Three findings decide the rest:

- **The diff is the source of truth.** Describe what the branch ships — including the
  commit you forgot — not what you remember working on.
- **A repo template wins.** If `.github/` defines a PR template, fill *its* sections in
  *its* order, and carry this skill's discipline into whatever slot asks for testing or
  verification. The shapes below apply only when the repo has none.
- **An existing PR means update, not create.** Step 5 edits it in place; never open a
  duplicate. If the body already matches what the branch now ships, exit — nothing to do.

## 2. Decide the shape

One question: does the branch **restore intended behavior** (bug fix) or **change or
extend it** (feature)? Mixed branches lead with the dominant shape and carry the
remainder under Notes. Edge cases (refactors, mixed branches): `./pr-patterns.md`.

## 3. Fill the sections — exactly these, in this order

**Bug fix:**

1. **Problem** — the user-visible symptom, in plain words: what broke, who hit it.
2. **Root cause** — the mechanism actually found, not the first suspicion.
3. **Fix** — what changed, and why this way.
4. **Tests** — coverage added or extended; name the test that now catches the bug.
5. **Verification** — the commands run and their observed output. Evidence, never
   claims (`./pr-patterns.md`).
6. **Notes** — tradeoffs, follow-ups, review hints.

**Feature:**

1. **Summary** — two or three sentences a CTO reads first: what ships, why it matters.
2. **Problem** — the need, in plain words: what couldn't be done before.
3. **Solution** — the approach chosen; the rejected alternative in one line when the
   diff or commits record one — "Rejected: none recorded" is honest too.
4. **Implementation** — the shape of the change in the code: key files, seams touched.
5. **Tests** — coverage added or extended.
6. **Verification** — commands run and observed output.
7. **Notes** — tradeoffs, follow-ups, review hints.

Both shapes close with the merge checklist, posted unticked:

```markdown
## Before merge
- [ ] Manual review
- [ ] Smoke tested
- [ ] Pipeline green
```

A box is ticked by whoever verified it — the reviewer for the manual read, the author or
CI for the rest. A pre-ticked box with nothing behind it is decoration, not evidence.

No invented headings, no omissions: content that fits no section goes under Notes or
stays out. For Verification, run the commands *now* and paste the lines that prove the
point; anything not run is declared — "Not run: needs staging" — an honest gap beats a
fabricated pass. Write the assembled body to `/tmp/pr-body.md`; step 5 posts that file.

## 4. Self-check against the audience contract

Read the draft as the three readers of `../_shared/audience.md`:

- **Junior** — can they follow Problem → Fix (or Solution) without tribal knowledge?
  Every internal codename expanded on first use?
- **Senior** — does every claim have its evidence under Tests or Verification? A bare
  claim gets its proof moved in, or gets softened to what the evidence supports.
- **CTO** — do the headings and first lines alone carry outcome and risk?

Plain prose throughout. A sentence that reads like a release announcement gets rewritten
as a fact.

## 5. Create or update

Show the title and body for approval first — pushing and opening a PR publish the draft.

```bash
git push -u origin HEAD               # if not yet pushed
gh pr create --title "<subject>" --body-file /tmp/pr-body.md
# or, when step 1 found an existing PR:
gh pr edit <number> --body-file /tmp/pr-body.md
```

The title carries the branch's dominant commit subject; a subject past ~72 characters
is compressed — keep the `type(scope):` and the one concern
(`../write-commit-messages/SKILL.md`). Editing the existing body in place is this skill's idempotency: a re-run regenerates the
description from the current diff and lands on the same PR.

## 6. Verify

```bash
gh pr view
```

Expected: one PR for the branch; six (bug fix) or seven (feature) sections in the fixed
order, closed by the Before-merge checklist — or the repo template's own; every
Verification entry is a command plus its observed output, not an adjective.

## References
- ./pr-patterns.md — why evidence beats assertion, Problem vs Summary, the shape decision, a filled example, when to deviate.
- ../_shared/audience.md — the junior-to-CTO contract step 4 checks against.
- ../write-commit-messages/SKILL.md — the commit subjects the title and Summary draw from.