The deploy broke billing for forty minutes. Everyone is relieved it is over, everyone is tired, and now someone has to write the postmortem. The temptation is a document that says “a mistake happened, we fixed it, we will be more careful.” That document is worse than none: it performs learning without doing any.
A postmortem that changes things has three sections, and each has a rule.
Timeline: facts, in order, with timestamps#
When did monitoring fire, who saw it, what did they try, when did recovery start. Written from logs and chat history, not memory - memory edits itself within hours. The timeline is where you discover the real story: the alert that fired twenty minutes before anyone looked, the rollback that took fifteen minutes because nobody remembered the command (which is why rollback or roll forward exists as a pre-made decision, not an improvised one).
Rule: no judgments in the timeline. “Deployed v2.3.1 at 14:02” is a fact. “Deployed carelessly” is a verdict, and verdicts here make people defensive before you reach the part that matters.
Contributing factors: plural, and never a person’s name#
“Stefan merged the bad migration” is not a cause; it is a scapegoat. The contributing factors are the things that made the mistake easy and its blast radius large: migrations deploy without a dry run, the billing smoke test only runs hourly, one person holds the rollback knowledge. Any of these could bite a different person next week, which is exactly why they are the fixable layer.
Rule: if a factor cannot be assigned to a system, a process or a missing safeguard, keep digging.
Actions: owned, dated, small#
Every action has one name and one date. “Improve testing” is a wish; “Amira adds a billing smoke test to the deploy pipeline by Nov 7” is an action. Three real actions beat ten aspirational ones - and they go in the tracker, not just the document, because a postmortem action without a ticket is a hope.
Rule: review the actions at the next incident review or team meeting. An action that slips twice gets escalated or honestly dropped; silently forgotten is the one outcome that teaches the team postmortems are theater.
Write it within two days, share it where everyone can read it, and thank the people named in the timeline - they are the ones who told you the truth.
Share this post
Keep reading
A First CI Pipeline for a Laravel Project
Install, lint, test, build - four jobs that run on every pull request and turn 'works on my machine' into a check everyone can see.
A Staging Environment Worth Having
Staging only catches what it shares with production. Same deploy path, same services, sanitized data - and a clear rule for what it is for.
Branch Naming Conventions That Scale Past Three People
Branch names are a user interface for your team's work. The conventions that survive growth, the ones that collapse, and why boring always wins.
