A postmortem people read is short, has a timeline with real timestamps, avoids naming anyone as a cause, and ends with three or four actions that have owners and dates. Most postmortems fail on the last part. They produce a document with a root cause section, a list of twelve improvements nobody owns, and a general feeling that lessons were learned. Six months later the same incident happens and somebody finds the document.
Blameless means something specific
Not that nobody made a mistake. Someone usually did. Blameless means the document treats the mistake as evidence about the system rather than about the person, because a system where one tired person at five o’clock can break production is the actual problem.
The practical test: replace every name with “an engineer” and see whether the document still explains what happened. If it does, you have written it correctly. If it now says nothing, you wrote an account of who was at fault.
The phrasing matters more than people think. “The deployment was not validated against the full test suite” describes a gap. “Sarah skipped validation” describes a person, and it teaches everyone reading it to be less forthcoming next time. You only get accurate postmortems from people who are not worried about them.
What goes in it
A summary, four sentences. What broke, who was affected, for how long, and whether it is fixed. Most readers stop here and that is fine, so make these four sentences carry the weight.
Impact in numbers. 340 users unable to save a case for 70 minutes. 11,200 records with an incorrect owner. Two days of integration messages queued. Vague impact makes the whole document easy to dismiss.
The timeline. The heart of it. Timestamps, what happened, who knew what, in plain sequence. Include the gaps honestly: if it was 40 minutes between the first user report and anyone looking at it, that goes in, because that 40 minutes is usually where the biggest improvement is hiding.
What actually caused it. Usually several things that were individually harmless. The change, plus the reason it was not caught, plus the reason nobody noticed for an hour. A single root cause is nearly always a sign that the analysis stopped early.
What went well. Not decoration. If an alert caught it or a kill switch worked, that is something to protect.
Actions. Covered below, and the only part that changes anything.
Writing the timeline
Gather evidence before memories settle. Setup Audit Trail, deployment history, Apex job records, debug logs, the chat channel where people were talking during it, and the integration logs at the other end. On Salesforce, the Setup Audit Trail is frequently the single most useful artefact and almost nobody exports it during the incident.
Write what people believed at each point, not only what was true. “At 14:20 the team believed the integration was at fault” explains the next forty minutes better than a correction does. Postmortems recording only the truth make the response look irrational.
Actions that survive
- Three or four, not twelve. A list of twelve is a list of zero. Pick the ones that would have prevented this or halved the detection time.
- Named owner, not a team. “Platform team” owns nothing.
- A date, and a ticket in the normal backlog. Actions that live only in the postmortem document do not happen.
- Prefer prevention to process. “Add a required check in the pipeline” beats “be more careful when deploying” every time, because the first one works when someone is tired.
- Include detection. If it took an hour for anyone to notice, an action about monitoring is worth more than an action about the cause.
When to write one at all
Anything affecting users for more than a few minutes, anything involving data corruption, anything where the response itself was messy even if the impact was small. Near misses are worth writing up and almost never are, which is a shame, because a near miss gives you all the learning for none of the cost.
Hold the meeting within a week while people remember, keep it to 45 minutes, and have the draft written before it so the meeting corrects a document rather than producing one from scratch.
Frequently asked
Who writes it? Someone who was involved, reviewed by someone who was not. The outsider catches the assumptions the participants cannot see.
Should customers see it? Sometimes a summary, rarely the full document. Decide before you write, because writing for two audiences at once produces something useless to both.
What if the cause was a Salesforce platform issue? Still write it. Your detection time, your communication and your workaround are all yours, and those are the parts you can improve.
