Write the pull request for the reviewer

Why this rule exists

A pull request is a piece of writing aimed at a specific reader, the person who has to understand and approve your change, and treating it as an afterthought wastes their time and yours. The diff shows what changed; only your description can explain why, what you considered and rejected, and where you're least sure and most want eyes. A good description turns review from an archaeology dig into a guided tour, which means faster, better review and fewer rounds of confused back-and-forth. It's also a lasting record: six months from now, someone running git blame on a strange line will land on your PR, and whether they understand the change depends entirely on what you wrote today. Making the reviewer's job easy isn't a nicety, it's how you get thoughtful review instead of a reluctant approval, and thoughtful review is the whole reason we do this. The few minutes you spend writing it up are repaid many times over.

In practice

Open with what this change does and why, in plain language, before anyone reads a line of code. Explain the context and the approach, and flag the tradeoffs you made and the parts you're unsure about, so the reviewer knows where to look hardest. Point out anything non-obvious, and pre-empt the questions you'd ask if you were reviewing it. Keep the change focused, and if you snuck in an unrelated cleanup, say so or split it out. Include how you tested it, and link the issue or decision record that motivated it. Then read your own diff before requesting review, catching the embarrassing stuff yourself so the reviewer can spend their attention on things that matter.

Example

## What & why
Adds retry with backoff to the payments webhook.
We were dropping ~2% of events on transient 503s
from the provider (see incident 2026-05-30).

## Approach
Exponential backoff, 3 tries, jittered. Chose this
over a queue because volume is low and a queue is
more machinery than the problem needs right now.

## Not sure about
The max-retry cap of 3 — open to 5. Flagging.

## Testing
Unit tests for backoff math; manually forced 503s
against staging and confirmed redelivery.

When it doesn't apply

A truly trivial change, a typo fix, a version bump, doesn't need an essay; match the description to the weight of the change. But err toward more explanation than you think you need, because what's obvious to you mid-flow is rarely obvious to a cold reader.