Technical

Trace every cause of an incident to a fix

Give each contributing factor its own branch, follow it to the gap that let it happen, and end each branch on an action item.

Start from a template

A postmortem template you can clone. Fill in your own incident to run a blameless postmortem on it.

Clone this template

How it works

A postmortem has to explain an outage that had more than one cause and end on fixes someone will own. Put the incident at the root of the map, and every question you ask below it keeps the incident in context.

  1. Reconstruct the timeline. Describe what broke, when, how it was found and how it was fixed. Ask where the gaps are, such as stretches where nobody knew there was a problem.

  2. Give each contributing factor a branch. Say a deploy triggered the incident, missing alerts made it worse and an unclear runbook made it last longer. That is three branches, one per factor.

  3. Follow each factor to the gap behind it. “No connection pool alert” is a symptom. Keep asking why under it until you reach the gap in tooling, process or knowledge, such as having no monitoring checklist for new dependencies.

  4. End each branch on an action. Add an alert, update a runbook, or add a test to the pipeline. When one action closes gaps on two branches, do it first.

Each node’s model reads only the nodes above it. Put the alert times and the deploy log in the incident at the root, or attach a dashboard screenshot there, so every branch below can use them.

Why a map instead of a 5 Whys document

The 5 Whys format leads to a single root cause. An outage with a bad deploy, missing alerts and a slow rollback has three, and a map gives each its own chain of whys and its own action item.

Laying the factors out by area, such as process, tooling and monitoring, keeps the review on the system and off the person who pushed the change.

Example

Say your payment service was down for 90 minutes at peak traffic. The map branches into the timeline and three factors: a config change that turned off circuit breakers, a monitoring gap that missed the error spike for 20 minutes, and a runbook that pointed to a retired admin tool. Under the config change, you find it passed review because the reviewer did not know that file controlled circuit breakers, and passed staging because staging never gets enough load to trip them. Both lead to the same gap: nothing maps config keys to what they control. One action, a config registry with owners, closes both.

Now try it yourself

Run a postmortem for a 3-hour outage caused by a database connection pool leak after deploying a new ORM version
This incident has three layers to analyze: the triggering change (ORM upgrade), the amplifying factor (no connection pool monitoring alerts), and the prolonging factor (unclear rollback procedure). Map each layer to identify systemic improvements, not just the immediate fix.
Why didn't our existing alerts catch the connection pool exhaustion?
Most default database monitoring tracks query latency and error rates, not connection pool utilization. The pool filled gradually over 45 minutes — slow enough to stay below latency thresholds but fast enough to exhaust connections before the next on-call rotation check. You need a dedicated gauge for active_connections / max_connections with a threshold alert at 80%.

Ready to try incident postmortems?