Write PR Description

write-pr-description

A pull request description has one job: give the reviewer what the diff cannot.

The diff already states what changed. The description states why it changed, what it affects, which decisions were made along the way, and where the author wants attention. Everything below follows from that. When a rule here conflicts with what a specific reviewer needs, serve the reviewer.

create-pr covers the mechanics of opening the PR. This skill covers what goes in the body.

1. Collect the facts before drafting

Usually you did the work and already know most of this. When you are describing a branch you did not write, or a PR you have just been handed, start here.

# From a checkout of the branch
git --no-pager log <base>..HEAD            # commit bodies first, they carry the why
git --no-pager diff <base>...HEAD --stat

# From a PR number, with no local branch
gh pr view <n> --repo <owner/repo> --json title,commits,files,baseRefName
gh pr diff <n> --repo <owner/repo>

Read the commit bodies before the diff. They are usually the richest source of motivation. Then verify what they claim: a commit message saying "matches the existing pattern in this file" is an assertion about code, and it is often wrong. Do not forward a claim you have not checked.

Verify by looking, not by reasoning. The checks worth making are cheap and specific:

• Read what the change deletes. When a change exists to fix something, the defect is usually visible in the removed code.
• Ask the system what a thing means, rather than inferring it: gcloud iam roles describe for a role's permission set, the provider or API schema for a resource's fields, the parser for what a marker does.
• Grep a flag across the environment files before claiming it is on or off.
• Open the file a comment or commit message points at, and confirm it says what the pointer claims.

One check of this kind usually produces the best sentence in the description.

Gather what the diff cannot tell the reviewer:

• The motivation. What breaks, costs, or stays impossible without this change.
• The linked issue, spec, or design doc, and any spec files committed on the branch.
• Decisions with a real alternative, and why the alternative lost.
• The blast radius: what this can break beyond the files it touches.
• The validation you ran, and what it showed.
• Anything you are unsure of.

2. Follow the repository's template

Check the repository for a PR template. Where there are several, pick the one matching the change. Templates differ per repository, so check every time rather than reusing the shape from your last PR.

The template's own instructions outrank this skill. A template that says "remove this section if it is not relevant" is telling you what this repository's reviewers want. Follow it. The guidance below applies where the template is silent.

• Keep the headings, their wording, and their order. Reviewers and tooling both scan for them.
• Answer every section, in your own words, under the heading. Do not reproduce the template's question text, its explanatory links, or its examples. A template with four gate sections can otherwise cost two hundred words to say "no" four times.
• Where a section does not apply, say so in a clause that shows you considered it ("No new tables"), rather than deleting it or leaving it bare.
• Tick a box only when its statement is true. Otherwise leave it unticked with a short reason on the same line. Do not delete the box, do not tick it with a caveat attached, and do not restate the box's own text back to the reader.
• Preserve machine-read content: changelog markers, artifact or media markers, issue linking keys. Check that the marker is live where the template puts it. Some templates show a marker inside an HTML comment that the parser strips, which means a marker left in place is silently ignored. Confirm against the parser or a merged PR.
• Instructional HTML comments can go once you have answered them.

When no template exists, use this shape, which is the same shape a template would give you:

1. The opening paragraph from step 3, with no heading above it. It carries both what and why, so there is no separate Why section.
2. ## Review guide, when step 4 calls for one.
3. ## What changed
4. ## Validation

This shape collapses on a small change. A heading over a single line is the same ceremony step 4 warns about, so drop any section that would hold one and let the opening carry it.

3. Write the body

Open with one to three sentences covering what the change does and why. A reviewer who reads only the first paragraph should be able to tell whether they are the right reviewer.

Where the repository has a template, this paragraph goes inside its first content section, whatever that section is called. Do not add a lead above the template's first heading, and do not repeat it once inside.

Then give the substance:

• Explain the mechanism only where it is not obvious from the code. A new abstraction, a non-local invariant, or an unusual control flow needs a paragraph. A renamed field does not.
• Name behavior changes explicitly, including ones that are side effects of the main change. These are what break other people. For a permissions change, state the direction: what is now allowed that was not, and what is now refused that was allowed.
• Record decisions with their rejected alternatives. This is the highest-value content in most descriptions and it cannot be recovered from the diff. Where there was no real alternative, state the decision plainly. Do not manufacture one to fill the slot.
• Include visual evidence for a user-visible change: a screenshot, or before and after where the change is a modification. Reference only captures that exist.
• Link the issue, spec, or conversation once. Where there is none, say so only if the repository asks for one, through a template section or a contributing guide. Announcing "no linked issue" in a repository that does not use them is lint compliance rather than information. Never invent a plausible ticket ID to fill the gap; a wrong link costs more than no link.

Validation

You normally ran the work, so report it: the command and what it showed.

Where you did not, or only partly did, these are the honest shapes. More than one can apply at once: you may have verified a fact yourself and still be waiting on CI for the rest.

• Nothing ran. State it plainly and name the command the reviewer or CI should run.
• CI produces the result, because the check needs credentials or an environment you should not use. Name the job, and say what you expect it to show, marked as an expectation rather than an observation. "Expect one destroy and one create, nothing else" gives the reviewer something to check the run against, which is more useful than silence. Phrase it so it cannot be misread as output you saw.
• The branch adds tests but no run is recorded. Say the tests are added and unrun, so nobody reads the test list as evidence they passed.
• You could not run it, for want of a device, credentials, or an environment. Say so, and name it as a check you are asking the reviewer to make. This does not cover something you skipped; if you could have run it, run it.
• Someone else recorded the result, such as a verification noted in an earlier commit. Attribute it or leave it out. Never restate it as your own observation.

Whichever apply, state each once. Repeating "this was not run" in three sections reads as hedging, and buries the one line that says what to run instead.

Never write intent as though it were a result.

Prose

Use ASD-STE100 as the baseline: active voice, one topic per sentence, sentences under about 25 words, simple tenses, one term per concept for the whole description. Code identifiers, command lines, and established repository jargon are technical names; leave them alone. See references/plain-language.md for the rules and the exemptions.

4. Add reviewer guidance when it is warranted

Add a review guide when the reading order is not obvious, when you have a specific place you want attention, or when the change can break things well beyond the files it touches. Skip it when a competent reviewer will know where to look without being told.

Put it high, directly after the summary. A reviewer should not have to scroll past compliance checklists to find where to start. ## Review guide is a reasonable default heading when the template does not supply one.

On a small PR, guidance is a sentence or two, not a section. Fold it into the opening rather than raising a heading over it. A heading on two paragraphs is ceremony, and so is a reading order for six files.

A review guide contains some or all of:

• A recommended reading order, for PRs large enough that the order matters.
• Focus areas: what you are unsure of, security-relevant surfaces, decisions with a meaningful alternative, and one-way doors where the ambiguity is genuine.

Write it for a competent engineer. Point at the code and the open question; never explain how to review code. See references/review-guide.md, which opens with a short map of which of its sections you need.