Skip to content
Back to blog
Guides

How to run a blameless incident review that people actually read

Most post-mortems are written once, filed, and never opened again. A format that gets read — and changes what the team does on Monday.

Daniel Okoye

Engineering Manager, Platform

Published
Reading time
2 min
Two colleagues leaning toward a laptop screen, discussing something they are both pointing at
Photograph via Unsplash

A reliable sign that an incident review process is broken: nobody can name the last one they read. The documents exist. They are long, thorough, and linked from a wiki page that nobody visits. The incident is over, the action items have quietly expired, and the next incident will rhyme with this one.

Over the last two years we've rebuilt how we review incidents at Leaf. The format below isn't clever. It's just built around one question: what would make someone want to read this?

Start with the meeting, not the document

The document is a record of the review, not the review itself. Hold a short live conversation within five working days — 45 minutes, with the people who were actually involved — and write the document from it, not instead of it. The conversation surfaces what the timeline can't: what people believed at the time, and why it made sense.

Two people working side by side at a desk with laptops and notebooks
The best reviews we run feel like a pairing session about a shared problem.Photograph via Unsplash

Ground rules for the room

  • Nobody is the cause. If a person's action contributed, ask what made that action reasonable.
  • Describe, don't judge. "The deploy went out without a canary" rather than "X forgot the canary."
  • Ask how, not why. Why invites defensiveness; how invites a story.

A format that gets read

Keep every review to two pages. If it needs more, the extra material goes in an appendix that no one is obliged to read. The two pages follow a fixed order, so readers learn where to look.

  1. Summary — three sentences: what broke, who was affected, how long.
  2. Impact — in customer terms, with numbers.
  3. Timeline — short, in plain language, with the decision points marked.
  4. What we learned — the two or three insights, framed as surprises.
  5. What we're changing — at most five actions, each with an owner and a date.

Write the surprises first

The most valuable section is the one on surprises: the places where our mental model of the system turned out to be wrong. Those are the parts other teams actually learn from, so we put them above the timeline rather than below it.

Make it travel

Publishing is a feature, not an afterthought. Every review goes to a company-wide channel with a one-line summary, and the two most interesting are read aloud at our monthly all-hands. People read what they know others are reading.

The goal of an incident review is not to prevent that incident. It's to make the whole company a little harder to surprise.

A review that gets read, discussed and acted on is worth more than the best document no one opens. Start with the conversation, keep it short, and write down what surprised you.

Keep reading

All stories