| name | postmortem |
| version | 0.1.0 |
| description | Write blameless postmortems after incidents with timeline, root cause analysis, impact assessment, and action items. Use when the user mentions "postmortem," "post-mortem," "incident review," "root cause analysis," "RCA," "incident retrospective," "what went wrong," or wants to document lessons from a resolved incident. |
Postmortem
Write blameless, actionable postmortems that help teams learn from incidents — not assign blame.
When to Use
- "write a postmortem for yesterday's outage"
- "help me do an RCA for the API incident"
- "we need an incident retrospective"
- After using
incident-communication to resolve an incident
Workflow
1. Check for Context
Read .agents/status-page-context.md if it exists. Use it for:
- Component names — reference the correct service names
- Severity levels — classify the incident correctly
- Past patterns — check if this is a recurring issue
- Tone — match the team's communication style
If the file doesn't exist, suggest running the status-page-context skill first. Proceed without it if the user wants to skip.
2. Determine Audience
Ask the user who will read this postmortem:
| Audience | What to emphasize |
|---|
| Internal (engineering team) | Deep technical detail, code-level root cause, specific system names |
| Internal (leadership/cross-functional) | Business impact, timeline, prevention measures, resource asks |
| External (customers/public) | User impact, what was done, what's changing, trust rebuilding |
Default to internal (engineering team) if not specified.
3. Gather Incident Details
Ask for or extract from conversation:
Required (postmortem cannot proceed without these):
- What happened (high-level summary)
- When it started and ended (UTC)
- What was affected (components, users, regions)
- What caused it (root cause, even if preliminary)
- How it was fixed (mitigation steps)
Important (ask if not provided, mark [TODO] if unknown):
- Who detected it and how (monitoring alert, customer report, internal discovery)
- Timeline of key events (detection, escalation, diagnosis, mitigation, resolution)
- Quantified impact (error rates, affected users/requests, revenue impact)
- Contributing factors beyond the root cause
Optional (include if available):
- On-call responders and roles
- Links to relevant logs, dashboards, PRs
- Screenshots or graphs showing the impact
4. Write the Postmortem
Use the template below. Fill in what you can from the information provided. Mark unknown sections with [TODO: description of what's needed] — never invent details.
5. Review Checklist
Before delivering, verify:
Postmortem Template
# Postmortem: [Incident Title]
**Date:** [YYYY-MM-DD]
**Severity:** [Critical / Major / Minor]
**Duration:** [X hours Y minutes] ([start time] – [end time] UTC)
**Authors:** [TODO: who wrote this postmortem]
**Status:** Draft
---
## Summary
[2-3 sentences: what happened, what was affected, how long it lasted, and how it was resolved. Written so someone skimming only this paragraph gets the full picture.]
## Impact
- **Affected components:** [list]
- **User impact:** [what users experienced]
- **Duration:** [start] – [end] UTC ([total duration])
- **Blast radius:** [% of users/requests affected, regions, plans]
- **Data loss:** [yes/no — if yes, describe scope and recovery]
- **SLA impact:** [did this breach any SLA commitments? error budget consumed?]
- **Financial impact:** [TODO: revenue loss, credits issued, if applicable]
## Timeline
All times in UTC.
| Time | Event |
|------|-------|
| [HH:MM] | [First sign of issue — how it was detected] |
| [HH:MM] | [Escalation — who was paged, who responded] |
| [HH:MM] | [Key diagnostic step — what was investigated] |
| [HH:MM] | [Root cause identified] |
| [HH:MM] | [Mitigation applied — what was done] |
| [HH:MM] | [Recovery confirmed — metrics returned to normal] |
| [HH:MM] | [Incident declared resolved] |
## Root Cause
[Explain the root cause in plain language. Go at least 2 levels deep with "why":]
**What happened:** [the direct technical cause]
**Why it happened:** [the systemic reason the direct cause was possible]
**Why that was possible:** [the deeper process/cultural/architectural gap]
[If multiple contributing factors, list each separately.]
## Detection
- **How was it detected?** [monitoring alert / customer report / manual discovery]
[minutes from start to first alert]
[did the right alerts fire? were they actionable?]
[what should have caught this sooner?]
[minutes from detection to first human action]
[minutes from detection to fix deployed]
[minutes from detection to incident closed]
[yes/no — if no, why not?]
[who was involved, was escalation timely?]
[Thing that worked — be specific]
[Thing that worked]
[Thing that worked]
[This section is important. Teams that skip it only learn what to avoid, never what to repeat.]
[Thing that didn't work — be specific about the gap, not about people]
[Thing that didn't work]
[Thing that didn't work]
[Thing that could have made this worse but didn't]
[Thing that limited the blast radius by chance, not by design]
[This section catches near-misses. If the incident had hit during peak traffic, during a deploy, or in a different region — would the impact have been worse?]
| Priority | Action | Owner | Due | Ticket |
|----------|--------|-------|-----|--------|
| P0 — must do | [Immediate fix to prevent exact recurrence] | [TODO] | [TODO] | [TODO] |
| P0 — must do | [Improve detection for this failure mode] | [TODO] | [TODO] | [TODO] |
| P1 — should do | [Systemic improvement to reduce risk] | [TODO] | [TODO] | [TODO] |
| P2 — nice to have | [Longer-term architectural improvement] | [TODO] | [TODO] | [TODO] |
[1-3 key takeaways that apply beyond this specific incident. What would you tell another team to watch out for?]
---
Blameless Writing Guide
Postmortems exist to improve systems, not punish people. Every sentence should pass the blameless test:
| Blameful (don't write) | Blameless (write this instead) |
|---|
| "Engineer X forgot to check the config" | "The deployment process did not include a config validation step" |
| "The on-call engineer was slow to respond" | "The alert routed to a secondary channel with a 20-minute delay" |
| "QA missed this bug" | "The test suite did not cover this edge case" |
| "Someone deployed without testing" | "The deploy pipeline does not enforce pre-deploy test runs" |
The rule: Replace the person with the system. If a human made an error, the system made it possible. Fix the system.
Root Cause Depth: The "5 Whys" Lite
A postmortem that stops at the first "why" is a bug report, not a postmortem.
Too shallow:
"The API went down because a bad config was deployed."
Deep enough:
"The API went down because a bad config was deployed (why?). The bad config was deployed because config changes are not validated before deploy (why?). Config validation doesn't exist because configuration is managed as raw JSON with no schema (root cause: no config schema or validation in the deploy pipeline)."
Go at least 2-3 levels deep. Stop when you reach a systemic gap that can be addressed with an action item.
Related Skills
incident-communication — Write status updates during the incident (before the postmortem)status-page-context — Set up the context document this skill reads (components, severity, past patterns)maintenance — Write planned maintenance announcementsstatus-report — Write periodic health reports
