PR discipline

A pull request is not the code. It is the unit a reviewer has to hold in their head while deciding whether to trust it. A diff can be entirely correct and still fail at that job: too large to review in one sitting, described by a story the diff no longer tells, or claimed ready when a check is still red. This is a working rule about the container, not the contents, alongside no-scripted-editing: how a change gets shaped so review actually works, independent of whether the code inside it is any good.

The shape of a mergeable change

Decide how many pull requests a piece of work needs before writing any of it. A change that mixes concerns a reviewer would naturally judge by different standards, schema against UI, backend against frontend, a mechanical rename against a behavior change, asks one reviewer to hold two mental models at once, and asks review to happen at the lower of the two bars.

When a change does not fit in one reviewable diff, stack it: an ordered chain of branches, each based on the one before, each carrying exactly one concern, each reviewable on its own. Foundational work goes at the bottom; whatever depends on it goes above. Plan the layers before writing code. Restructuring a stack after the fact costs more than starting split, since there is rarely a clean in-place reorder once commits already exist on the wrong branch.

A stack should read as one coherent story: a reviewer walking it bottom to top watches the feature get built. Unrelated work, a different feature, an incidental fix that has grown past incidental, gets its own stack rather than riding along because it happened at the same time.

The description matches the diff, not the intent

Write the title and body from everything the change currently does, not from the first commit or the plan it started as. A description is a claim about the diff, and the moment the two diverge, the reviewer is reviewing the wrong thing without knowing it.

Refreshing a description is not rewriting it from scratch. Anything a person added to it, a screenshot, a linked discussion, context that only ever existed in someone's head, survives the refresh untouched. Rewrite the prose around it, never over it.

An oversized, hard-to-follow diff does not get fixed by writing a longer description or annotating the risky parts. Notes can guide a reviewer through a diff that is already reviewable; they cannot make an unreviewable one reviewable. When the honest fix is splitting the change, say so instead of writing around the problem.