Postmortems

Philosophy

Postmortems are blame-free analyses of incidents — what went wrong and what we learned.

Given that,

a) most team members will (and probably should) write these with AI,

b) most team members won't read a fully specced out postmortem,

each postmortem has two layers:

1. TL;DR — written by a human, for humans. The curated takeaways of what actually matters. Concisely: what happened, what we learned, what we'd do differently.
2. Structured context — machine-generated. A full structured dump of the incident following templated sections like timeline, root cause and code references. AI agents consuming the repo can use this as context, and humans who want to deep-dive have everything they need. Clearly marked as machine-generated.

Guidelines

• Keep it neutral. Blame-free language — focus on systems and processes, not individuals.
• Use the template. The structure of the TL;DR is a suggestion — the author can write it however they see fit.
• The structured context may be machine-generated, but shouldn't be slop. The author is still responsible for sense-checking it.

Overview