
Start with the problem
One or two sentences on what was wrong or missing, in terms of what a user or another engineer experienced. Reviewers who do not know why the change exists will review the style, because that is all they can judge.
Show the change in reading order
- Data first. New tables, columns or types. Everything else depends on them.
- Then the main path. The one function or handler where the new behavior lives.
- Then the edges. Error handling, permissions, the old behavior you kept.
- Tests last. They are the summary of what you claim the change does.
Skip the renames and the formatting. Say that they exist and that they change nothing.
Say what you are unsure about
This is the most useful minute. "I am not sure the retry belongs in the consumer and not in the charge function" tells reviewers where to spend their attention. A change presented as finished gets a nod. A change presented with its open question gets a real review.
How it was tested, and how to undo it
- What you ran, and what you did by hand.
- What you did not test, said plainly.
- How to turn it off or roll it back if it misbehaves in production.
Ask specific questions
"Any thoughts?" gets silence. "Is two seconds a sensible timeout for this call?" gets an answer. Bring two or three questions like that and ask them by name if the room is quiet.
After the walkthrough
Write the decisions into the pull request itself, not into a chat that scrolls away. The next person to read this code will look there first.