The Pull Request Description Is the Specification

Here is the thesis. The pull request description is not a formality, not a summary, not a place for a ticket link. It is the specification, the only artefact in the review that states what the change is supposed to do and, more importantly, what it is not supposed to do, and a review that reads the diff without the description is checking an implementation against nothing, which is why such reviews approve the plausible and miss the wrong, and why the teams with good descriptions have measurably better reviews.

I am not arguing that descriptions replace tests or design docs. I am arguing that the description is the contract the diff is reviewed against, and that in its absence the review has no contract, and a review without a contract is a style check.

What the diff can and cannot say

The diff is a fact, the exact change, and it is authoritative about what the code now does locally, line by line. But the diff cannot say why, cannot say which behaviour is the point and which is incidental, cannot say what was considered and rejected, and cannot say what must never happen, and those four omissions are precisely the information the reviewer needs, because the reviewer's job is to detect the change that violates an intent, and the intent is not in the diff.

The tests add a second fact, what was checked, but the tests, like the diff, state behaviour, not intent, and a test suite can be comprehensive against the wrong specification, which is the mirror image of a test that restates the implementation is not a test, which is why the two fixes look alike.

The description as the review's contract

When the description states the intent, the review becomes a verification: does the diff do what the description says, does it do anything the description does not mention, and does it respect what the description says it must not touch. The second question is the powerful one, the unmentioned change, because a diff that contains more than the description describes is a diff with an unreviewed remainder, and the remainder is where the smuggled change lives, the formatting diff's lesson from the formatting only pull request that changed behaviour, generalised: the described change is reviewed, the undescribed change is not, so the description's completeness defines the review's surface.

The description also carries the negative space, the must nots, the invariant the change preserves, and the negative space is the part the incident reads later, because the postmortem's first question, what was this supposed to do, is answered by the description, and when the description is absent the postmortem reconstructs the intent from the diff, which is archaeology, and archaeology is what the description would have made unnecessary.

The counterargument, fairly

The honest defence of the light description is that writing is expensive and the code is self documenting, and a senior reviewer can read intent from a well named diff, and for small changes the description is overhead. I accept it for the small change, and the threshold is the point: the description's cost is constant and its value scales with the change's ambiguity, so the discipline should be proportional, a one line change earns a one line description, and the large or subtle change earns the contract.

There is also the reality that descriptions rot, a stale description is worse than none because it misleads, and the rot is real. The counter to the rot is that the description is reviewed with the diff, because it is part of the change, and a description that disagrees with the diff is a review comment, which keeps it honest the way the diff is kept honest.

What a contract description contains

The good description is short and structured, and it contains four things, each a sentence or two.

The intent: what the change makes true that was not true before, stated as behaviour, not as implementation. The non goals: what the change deliberately does not do, which is the negative space, and the reviewer's guard against scope creep in either direction. The invariants: what must remain true, the contracts the change touches but preserves, which is the property the reviewing code the author cannot explain checklist interrogates, pre answered. And the verification: how the author knows, the test, the manual run, the metric, which is the evidence the review audits.

Four sentences, and the review has a contract, and the reviewer's attention goes to the deltas between the contract and the diff, which is where the signal is, instead of a line by line walk, which is where the attention dies.

The uncomfortable conclusion

The teams with light descriptions are not saving time, they are moving the cost to the reviewer, who reconstructs the intent at a higher rate, with lower fidelity, and then to the postmortem, which reconstructs it at the highest rate of all, and the reconstruction at each stage is lossy, so the intent that was never written is progressively less true each time it is reconstructed, and the description is the only point where the intent exists at full fidelity, which is why its absence is not a small tax but a compounding one.

The description is also the ownership artefact, per AI wrote it so nobody owns it, which is why the two fixes look alike.

The thumb rule I use

The diff is the fact, the tests are the checked subset, and the description is the specification, the intent, the non goals, the invariants and the verification, against which the diff is reviewed, so treat the description as part of the change, review it with the diff, and scale its depth to the change's ambiguity.

A review without a description is a contract reading with the terms page missing, and the approval it produces is a verdict on the typography, not the terms, and the terms, unreviewed, are exactly what the incident enforces later, at which point the missing page is the first thing the postmortem wishes for, which is the description's entire job, performed too late.

Published on debugly.dev by Rohit Bhadani | Founder of Krova Cloud