Pull request template best practices: write for the reviewer, not the ritual
Othman Shareef · September 14, 2026 · 7 min read
Most pull request templates are written for an imaginary audit and abandoned by everyone else. Twelve checkboxes, a testing matrix nobody fills honestly, a screenshot section for a backend repo. Pull request template best practices start from a different question: what does the reviewer need to do a good job in the next fifteen minutes? A template is not a compliance form. It is the cheapest tool you have for moving context from the head of the author, who has it, to the reviewer, who does not.
Pull request template best practices: write for the reviewer
The audience for a template is not the author, not the auditor, and not the process document. It is the reviewer, fifteen minutes from now, deciding where to spend limited attention. We have written about why pull requests are hard to review, and the answer is mostly missing context: the diff shows what changed but not why, not what was considered and rejected, not which files carry the risk. A good template is a context pump aimed at exactly those gaps. Every prompt should be answerable in a sentence or two and useful to the person reading the diff. If a prompt exists to prove diligence rather than to transfer context, it is decoration, and reviewers learn to scroll past decoration fast.
Four sections that earn their place
- What. Two or three sentences describing the change at the level of behavior, not files. The diff already lists the files.
- Why. The problem, the ticket, the constraint that forced this approach over the obvious alternative. This is the section future archaeologists will thank you for.
- How to review this. Where to start reading, which file is the heart of the change, what deserves scrutiny versus what is mechanical rename noise. SmartBear’s peer review guidance found that authors who annotate their changes before review trigger better reviews, partly because annotating forces a self-review pass. This section is that annotation, structured.
- Risk. What could break, how you would notice, and how to roll back. One honest sentence here outperforms ten ticked checkboxes.
Template rot: twelve checkboxes nobody ticks honestly
Templates die by accretion. Every incident adds a checkbox, no retro ever removes one, and within a year the template is a wall of prompts that authors fill with “N/A” and reviewers skip wholesale. Worse than useless, rotten templates train both sides that the description block is noise, so even genuine context gets ignored. You can watch the rot progress in three stages: first authors answer every prompt, then they answer the first two and paste dashes into the rest, then a well-meaning contributor deletes the template block entirely and nobody objects, because it stopped carrying information months ago. A ticked box that was never honestly checked is the same pathology as the rubber-stamp approval we described in LGTM culture: process theatre that consumes credibility without producing safety. The maintenance rule is simple and almost nobody follows it: when you add a prompt, remove one, and once a quarter, delete any prompt whose answers you cannot remember a reviewer ever using.
AI-era additions: provenance and intent
Two prompts have become worth their cost since code generation went mainstream. First, provenance: which parts of this change were AI-generated, and what level of self-review have they had? Not as a purity test, but because reviewers calibrate differently for generated code, and they should get to. Second, intent: what did you ask for, and what did the tool decide on its own? The reasoning behind a generated change lives in a prompt session that will not exist next week; the PR description is the last cheap place to write it down, which is the argument we made at length in capturing intent for AI changes. Both prompts together are three lines of template. Skip the temptation to add an AI checklist section; two honest sentences beat a compliance block here too.
Keep it under eight prompts
The binding constraint on templates is not thoroughness, it is the author’s patience multiplied by the reviewer’s. Under roughly eight prompts, authors answer thoughtfully; past that, they paste boilerplate, and one boilerplate answer teaches reviewers to distrust all of them. Four core sections, two AI-era lines, and maybe one repo-specific prompt (migrations, screenshots, whatever your codebase genuinely bleeds on) is the whole budget. If a category of information matters only sometimes, do not add a prompt that is “N/A” the rest of the time; trust authors to add sections when relevant. The same budget logic applies per section: a heading with a one-line hint beats a heading with three sub-questions, because authors answer the hint and ignore the sub-questions anyway. Templates are also repo-scoped, so resist the org-wide mega template; the sections a mobile app needs are dead weight in a terraform repo. Finally, treat any template change like code: propose it, try it for a month, and keep it only if reviews measurably went better. The best template is the shortest one your reviewers actually read.