PR description

The reader is the reviewer: someone who knows the codebase, not how this change was made, and has no reason to care how it was made. They read the description to decide whether the change should exist, where to look, and whether they can trust that it works, and then they read the diff. So the description is a map of the diff. It gives what the diff cannot show and points to the rest. Every sentence answers one of those questions with something the diff and the documents the change updates do not already say, and every claim is one the reviewer could check. The job ends when a fresh agent that saw none of the work has verified it.

1. Gather

Work from what outlives the work: the final diff against the base, the commits, the issue the change closes, the documentation and ADRs it adds, and verification you ran on the final state. Read the whole diff. Notes from how the change was made, such as a spec, a plan, a review, a spike, or a report to whoever asked for the work, supply facts; the structure and the words come from the reviewer's questions.

Keep a claims list: each fact you may state, with its source.

• Diff: the file and lines that show it.
• Run: a command or action you ran on the final state, with its output.
• Said: a person told you, such as the owner's decision or report. The description attributes it to them.
• Document: a page or file you read, with where it lives and its visibility.
• Inference: your own conclusion. The description states it as one, or leaves it out.

A claim from an earlier run, from the change's own documents such as an ADR, or from an agent's report is a lead until the diff or a new run backs it. When the change moved after its description was written, such as after a review round, the old description is a lead too, so gather again from the final diff and write the description whole.

Done when you can say in one sentence why the change exists, and every claim you mean to make is on the list with its source.