Incident postmortem: how to write one from the evidence
How to write a blameless incident postmortem: one timeline from every source, measured impact, causes backed by evidence and follow-ups with owners.
Free app. Runs on your Mac with the Claude or Codex plan you already have.
What an incident postmortem is
An incident postmortem is the written review a team produces after an outage or a serious failure. It records what happened in time order, how long customers were affected, why it happened and what will change so it does not happen again. A good one is short enough to discuss in a single meeting and precise enough that every claim can be checked.
A blameless postmortem describes roles, systems and decisions, not individual faults, because people who fear blame hide the details the team needs. Blameless does not mean nobody is accountable: follow-ups still have owners. The method below is how an experienced incident responder writes one from alerts, logs, deploy history and chat. Each step says what to do and why, then how 10folds carries it out.
What it does for the business
- Stop the same incident twiceFollow-ups tied to evidenced causes change the conditions that allowed the failure. The next similar change is caught by a check instead of by customers.
- Shorter, calmer review meetingsWhen the timeline and figures are prepared and sourced, the meeting spends its time on decisions instead of arguing about what happened when.
- Learn how fast you respondTime to detect, acknowledge, identify the cause and mitigate, each measured from real events, shows where the response was slow and where it worked. Those measurements give the team a fair baseline for the next incident review.
- Honest communication with customersImpact figures drawn from data, with unverified numbers labelled, give support and leadership something accurate to say.
Incident postmortem, step by step
Build one timeline from every source
Most arguments about cause are really arguments about sequence.
What to do
- Gather alerts, logs, deploy history, chat or call notes, status page updates and support tickets for the incident.
- Establish the time zone of each source from its timestamps, its export header or someone who knows.
- Convert every event to one zone, usually UTC, and sort them into one incident timeline.
- Mark events that appear in two sources, and list quiet gaps where nothing was recorded.
- Fix sources that did not parse instead of dropping them.
Why
Evidence after an incident is scattered across tools that each use their own clock. A chat export with clock times only and a log in UTC can put the fix before the failure if the zones are guessed. Quiet gaps matter too: they often hide the decision that took longest. Marking the same event seen in two sources also helps confirm that the clocks were converted correctly.
Mark the moments that matter and measure impact
A duration is only as good as the two events that bound it.
What to do
- Mark the trigger, first customer impact, detection, acknowledgement, declaration, cause identified, mitigation, recovery and resolution.
- Compute time to detect, time to acknowledge, time to identify the cause and time to mitigate from those lines.
- State the impact window and which events bound it.
- Take user impact, such as failed requests or orders, only from the data.
- Attribute numbers quoted in chat to whoever said them, and mark them unverified.
Why
Estimated times drift toward the story people remember. Measuring from timeline lines makes the figures repeatable and shows exactly where the response lost time. A number someone typed in chat during the incident is useful, but it is not data until the source behind it is checked. Gaps in the record belong in the document as gaps, because filling them from memory turns a guess into history.
Establish the causes
Do not force a root cause the evidence does not support.
What to do
- Separate the direct cause from contributing factors: what allowed it, and why detection or response took the time it did.
- Cite at least one timeline line for every causal statement.
- Label each cause supported when independent sources agree or the working fix confirms it, otherwise hypothesis.
- When accounts conflict, show both with their sources and the check that would settle it.
- Ask what made the mistake easy to make, never who made it.
Why
Root cause analysis that stops at one cause misses the conditions that turned a small error into an outage. Labelling hypotheses honestly keeps the team from fixing the wrong thing with confidence. Treating human error as a symptom of missing checks, alerts or runbooks is what keeps a postmortem blameless and useful.
Draft follow-ups that would have changed this incident
A follow-up without an owner and a check is a hope.
What to do
- Type each follow-up as prevention, detection, mitigation or coordination.
- Write it specifically enough to act on, such as "CI rejects pool settings below the agreed floor".
- Give it an owner by role and a done-when check.
- Keep three to six, and drop any that would not have changed this incident.
- Leave due dates for the review meeting unless you were asked to propose them.
Why
Vague action items such as "improve testing" are never finished. A typed list shows whether the team is only preventing, or also detecting and responding faster. A short list gets done; a long one is quietly abandoned. Asking whether each item would have changed this incident keeps the list honest and stops it turning into a general wish list.
Check the draft, then hold the review
Every line of the timeline should be findable in its source at the stated time.
What to do
- Check that each timeline line exists in its source at the converted time.
- Check that each figure is computed from the cited events and each quote matches its source.
- Check that causes are labelled correctly and disputed facts shown both ways.
- Remove any sentence that blames a person.
- Bring the open questions to the review meeting and decide dates there.
Why
A postmortem becomes the official memory of the incident. One wrong time or misattributed quote undermines the whole document and can unfairly mark a person. A reviewer with only the draft and the evidence catches what the writer assumed. Deciding dates in the meeting, with the owners present, makes it far more likely the follow-ups are actually done.
Common mistakes
- Guessing time zonesOne wrong offset can reverse the order of cause and effect.
- Writing zero for missing impactZero is a measurement. No data is an honest gap.
- Naming a culpritBlame teaches people to hide details next time.
- Forcing one root causeMost incidents have a trigger and several contributing factors.
- Fifteen follow-upsLong lists without owners do not get done.
What a good result looks like
- One sentence that says what broke, for how long, why and how many follow-ups.
- A single timeline in one time zone, with the source of every line.
- Durations computed from named events.
- Causes labelled supported or hypothesis, each with a citation.
- Three to six follow-ups, each with a type, owner and done-when check.
And then what? Using the result
- Hold the review meeting with the draft and the open questions.
- Agree owners and dates for each follow-up.
- Import the follow-ups as tickets.
- Adapt the summary and impact sections for a customer or status page update.
- Reuse the structure as your postmortem template for the next incident.
When to run it
- After any incident with customer impactWrite it while logs are available and memories are fresh. A draft ready within a day keeps the review meeting focused.
- After a near missDefenses that worked are worth understanding before the next time they are needed.
- When the team disagrees about what happenedA sourced timeline settles questions of sequence and narrows the debate to what is really open.
- When the same kind of incident repeatsComparing causes and follow-ups across postmortems shows which fixes never landed.
Questions people ask
How do you write an incident postmortem?
Build one timeline from every source in a single time zone, mark the key moments, measure impact from the data, separate the direct cause from contributing factors with evidence, draft a few follow-ups with owners and checks, and have someone review it against the sources.
What is a blameless postmortem?
A blameless postmortem examines how systems, processes and conditions allowed an incident, without assigning personal fault. It assumes people acted reasonably with the information they had, so they share what really happened.
What should a postmortem include?
A one-sentence summary, the impact, a timeline, the direct cause and contributing factors, what helped and slowed the response, follow-up actions with owners and checks, and open questions.
When should you write a postmortem?
As soon as the incident is resolved, while evidence and memory are fresh. Teams usually write one for any incident with customer impact, and often for near misses too.
What if there is only a chat export?
The timeline is built from the chat, the postmortem says that system evidence was not supplied, and every system-side claim is marked as reported in chat. Impact counts are written as no data unless the figures behind them were supplied.
What if the cause is unclear?
The draft delivers the timeline and the hypotheses ranked by evidence, with the check that would confirm each, instead of forcing a root cause.
More jobs in Developers
Write an incident postmortem, on your own Mac.Free app. Runs on your Mac with the Claude or Codex plan you already have. Your files stay on your computer.
Download for Mac