Postmortems

Publish what happened after an incident — inline, or linked to a document you already have.

A postmortem is the follow-up your users see after a significant incident. It is the difference between “they went down again” and “they went down, and they clearly understand why”.

Two kinds

Use EXTERNAL when engineering already writes postmortems in your own system and you do not want two copies to drift.

Lifecycle

Postmortems get their own slug and can be linked to an incident, so readers of the incident find the write-up and vice versa. They can also be unlinked later.

Public URL:

/public/status/<page-slug>/postmortems/<postmortem-slug>

What to include

• What happened, in plain language.
• When, with a timeline including detection and recovery.
• Who was affected, and how — including who was not.
• Why it happened. The real reason, not the first trigger.
• What you are changing, specifically enough to be checkable.

Writing one that is worth publishing

• Be specific about impact. “Some users may have experienced issues” tells nobody anything. “Sign-in failed for roughly 40% of requests for 22 minutes” is useful.
• Blame systems, not people. A postmortem that ends at “an engineer ran the wrong command” has stopped one question too early — why was that possible, and why did nothing catch it?
• Only commit to actions you will do. An unfulfilled action item is worse than none, because the next incident makes it visible.
• Publish while people still remember. A postmortem three weeks later reads as an obligation rather than an explanation.