---
title: Postmortems
description: Publish what happened after an incident — inline, or linked to a document you already have.
sidebar:
  label: Postmortems
---

{/* Source of truth: packages/shared/src/status-pages.ts —
    PostmortemStatuses (DRAFT, PUBLISHED, ARCHIVED), inline body max 50k,
    external url. Routes: postmortems.* and
    public.statusPostmortem in packages/shared/src/routes.ts. */}

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

| Type | Content |
| --- | --- |
| `INLINE` | Markdown written in Glowo, up to 50,000 characters |
| `EXTERNAL` | A link to a document you host elsewhere |

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

## Lifecycle

| Status | Meaning |
| --- | --- |
| `DRAFT` | Not public. Write and review here. |
| `PUBLISHED` | Live on the status page |
| `ARCHIVED` | Retired from the default view, still retained |

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:

```http
/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.

:::note
Not every incident needs one. Reserve them for outages that were long,
widespread, or surprising — publishing a postmortem for a four-minute blip
devalues the ones that matter.
:::