Why write a post-mortem
A post-mortem is a written record of an incident: what happened, why, how it was handled, and what will change so it is less likely or less painful next time. Its purpose is learning, not blame. An incident is an unplanned experiment your systems ran on your behalf, and the write-up is how you extract the lesson before the memory fades and the same gap is stepped in again.
Write one for any incident that affected customers, took real effort to resolve, or surprised you — even a near miss. The habit matters more than the severity threshold.
Blameless by default
Blameless does not mean no accountability; it means assuming everyone acted reasonably given what they knew at the time, and focusing on the system that let a mistake cause an outage. When people fear blame they hide detail, and hidden detail is exactly what you need to fix the underlying problem. A culture that treats "human error" as the start of the investigation, not the end, gets far more honest post-mortems.
The template
Summary: two or three sentences a busy reader can absorb — what broke, who was affected, and for how long. Impact: which users and features, how many, and the business consequence. Timeline: a timestamped sequence from first symptom through detection, escalation, mitigation, and resolution. Detection: how you found out, and how long that took. Root cause: the chain of contributing factors, not a single culprit. Resolution: what actually stopped the bleeding. Action items: specific, owned, and dated follow-ups.
Timeline, detection, and impact
The timeline is the spine of the document, so capture real timestamps as you go rather than reconstructing them later. Two numbers usually fall out of it: time to detect (from the start of the problem to when you knew) and time to recover (from detection to resolution). A long time-to-detect points at monitoring gaps; a long time-to-recover points at tooling, runbooks, or access. Quantify impact in the terms your business cares about, whether that is failed requests, affected customers, or missed jobs.
Turn findings into action
A post-mortem that ends in insight but no change is entertainment. Every root cause and every "we got lucky" should produce a concrete action item with an owner and a due date, tracked like any other work. Watch for the pattern where detection was slow: the fix is often a monitor that did not exist — an assertion, a heartbeat, or a tighter threshold — so the next occurrence pages you in minutes instead of being reported by a customer.