what a good postmortem looks like — a worked example, with the 5 sections, in 30 minutes
a good postmortem takes 30 minutes to write. it has 5 sections. it is blameless. it is dated. it has follow-ups that are assigned and dated. here is the worked example, the template, and the 3 sentences you should never write in one.
a good postmortem takes 30 minutes to write. a good postmortem has 5 sections. a good postmortem is blameless. a good postmortem is dated. a good postmortem has follow-ups that are assigned and dated. a good postmortem is the artifact the dreamclerk cohort writes in week 8. a good postmortem is the artifact that gets you the cert.
this post is the worked example, the template, and the 3 sentences you should never write in a postmortem.
the 5 sections
1. summary (3 sentences)
the summary is the first 3 sentences of the postmortem. the summary answers: what happened, who was affected, what was the duration.
example:
on 2026-06-18 at 14:32 IST, the dreamclerk in-browser ide cold-start time regressed from 200ms to 4,200ms. 142 cohort 3 applicants were affected. the regression was detected at 16:45 and reverted at 17:20.
the summary is the only section most people will read. the summary is the only section that needs to be 100% accurate. the summary is the section the founder reads.
2. timeline (all times IST or UTC, dated)
the timeline is a list of every event that happened, in order, with a timestamp. the timeline answers: when did the incident start, when was it detected, when was it mitigated, when was it resolved.
example:
- 2026-06-04 11:00: PR #1284 opened.
- 2026-06-04 14:32: PR deployed to production.
- 2026-06-04 14:32–16:45: 142 applicants affected.
- 2026-06-04 16:45: feedback ticket filed.
- 2026-06-04 17:20: revert deployed.
the timeline is the section that survives the longest. the timeline is the section the lawyer reads. the timeline is the section the on-call engineer reads. the timeline is the section that should be the most boring section of the postmortem.
3. contributing factors (numbered, 3–7 items)
the contributing factors are the things that, together, caused the incident. the contributing factors are not the root cause. the contributing factors are the conditions that made the root cause possible.
example:
1. no perf benchmark in CI.
2. no canary deployment.
3. side-effect import not caught in code review.
4. cohort feedback not routed.
5. cold-start time not monitored.
the contributing factors are the section that takes the most thought. the contributing factors are the section that the next postmortem references. the contributing factors are the section the rubric is built from.
4. root cause (1 sentence)
the root cause is the single thing that, if you fixed it, would have prevented the incident. the root cause is the thing all the contributing factors point to.
example:
the root cause is the absence of a perf benchmark in CI. every other contributing factor is downstream of the missing benchmark.
the root cause is one sentence. the root cause is the sentence the next engineering hire reads. the root cause is the sentence the cohort writes in week 8.
5. what went well, what did not, follow-ups
the "what went well" is 2–4 items. the "what did not" is 2–4 items. the follow-ups are 3–7 items, each one assigned to a person, each one with a due date.
example follow-ups:
- [F1] add a perf benchmark to CI. owner: eng-1. due: 2026-06-15.
- [F2] lower the bundle size check. owner: eng-2. due: 2026-06-12.
- [F3] add a 10% canary. owner: eng-1. due: 2026-06-20.
the follow-ups are the section that survives the incident. the follow-ups are the section the on-call engineer tracks. the follow-ups are the section the cohort references in week 12.
the template
copy this. fill in the blanks. publish within 5 business days of the incident.
# [incident name] — [date]
## summary
[3 sentences. what happened, who was affected, what was the duration.]
## timeline
- [YYYY-MM-DD HH:MM]: [event]
- [YYYY-MM-DD HH:MM]: [event]
- ...
## contributing factors
1. [factor 1]
2. [factor 2]
3. [factor 3]
...
## root cause
[1 sentence. the single thing that, if fixed, would have prevented the incident.]
## what went well
- [item 1]
- [item 2]
...
## what did not go well
- [item 1]
- [item 2]
...
## follow-ups
- [F1] [action]. owner: [name]. due: [YYYY-MM-DD].
- [F2] [action]. owner: [name]. due: [YYYY-MM-DD].
...the 3 sentences you should never write
sentence 1: "X should have known better."
the postmortem is blameless. the postmortem does not assign blame to a person. the postmortem assigns the cause to a system. "X should have known better" is the sentence that turns the postmortem into a firing memo. write the sentence as "the system did not surface the risk to X" instead.
sentence 2: "this was a one-off, it won't happen again."
the postmortem is not a one-off. the postmortem is a pattern. the pattern is in the contributing factors. the pattern is the root cause. the pattern is the follow-ups. if you write "this was a one-off," you have not understood the postmortem. write the sentence as "the follow-ups below are designed to prevent the pattern, not the specific incident" instead.
sentence 3: "we have always done it this way."
the postmortem is a chance to change the way. the postmortem is not a defense of the way. the postmortem is the artifact that says "the way is broken, here is the new way." if you write "we have always done it this way," you have not understood the postmortem. write the sentence as "the way is broken, here is the new way" instead.
how to write one in 30 minutes
minute 0–5: the summary
open the doc. write the 3 sentences. the 3 sentences are the hardest part. the 3 sentences are the section the founder reads. the 3 sentences are the section the rubric scores on "specificity."
minute 5–15: the timeline
open the on-call channel. copy the events. paste them with timestamps. the timeline is the section the lawyer reads. the timeline is the section that should be the most boring section of the postmortem. the timeline should take 10 minutes, not 30.
minute 15–20: the contributing factors
the contributing factors are the section that takes the most thought. the contributing factors are the section the next postmortem references. the contributing factors are the section the rubric is built from. spend 5 minutes on the contributing factors. the contributing factors are the section that should be the most thoughtful section of the postmortem.
minute 20–25: the root cause + what went well + what did not
the root cause is 1 sentence. the "what went well" is 2–4 items. the "what did not" is 2–4 items. the 3 sections together take 5 minutes. the 3 sections are the section the cohort references in week 12.
minute 25–30: the follow-ups
the follow-ups are the section that survives the incident. the follow-ups are 3–7 items. each follow-up is a person, an action, a due date. the follow-ups take 5 minutes to write. the follow-ups take 5 weeks to do. the follow-ups are the cert.
what the cohort writes in week 8
the dreamclerk cohort writes a postmortem in week 8. the postmortem is the artifact. the postmortem is the cert. the postmortem is the signal. the postmortem is the 5 sections. the postmortem is the 30 minutes. the postmortem is the 3 sentences you should never write. the postmortem is the follow-ups that are assigned and dated.
the postmortem is the artifact. the artifact is the cert. the cert is the signal. the signal is the postmortem.
— dreamclerk team, chennai, july 2026