# Postmortem Writing

> Write blameless incident postmortems—timeline, impact, root cause, contributing factors, and actionable follow-ups. Use after outages, SEV incidents, or significant near-misses.

- Skill: `charlieviettq/postmortem-writing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add charlieviettq/postmortem-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charlieviettq/postmortem-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: charlieviettq (https://skillmd.com/u/charlieviettq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charlieviettq/postmortem-writing

---


# Postmortem writing

## Principles

- **Blameless** — focus on systems and process, not individuals.
- **Accurate** — timeline in UTC with evidence (logs, deploys, tickets).
- **Actionable** — every finding maps to owner + due date or ticket.

## Required sections

1. **Summary** — what happened, duration, user/business impact
2. **Timeline** — detection, escalation, mitigation, recovery
3. **Root cause** — technical chain; distinguish trigger vs underlying gap
4. **Contributing factors** — process, monitoring, dependency, change management
5. **What went well**
6. **Action items** — prevent recurrence, improve detection, reduce blast radius

## Timeline table

| Time (UTC) | Event |
|------------|-------|
| ... | Alert fired |
| ... | Mitigation applied |
| ... | Service restored |

## Action item quality

| Weak | Strong |
|------|--------|
| "Be more careful" | "Add alert on queue depth > X with runbook" |
| "Improve testing" | "Integration test for failover path in service Y" |

## Severity-appropriate depth

- SEV1/2: full postmortem + review meeting.
- SEV3/4: lightweight doc still with timeline and actions.

## Template

See [reference.md](reference.md) for full markdown template.

## Follow-up

Track action items to closure; link superseding ADRs or runbook updates.