Postmortems skill for Claude Code
Blameless reviews with numbers and owned actions. Claude rebuilds the incident timeline from alerts, deploy logs, chat and dashboards with a source for every entry, quantifies customer impact and error budget burn, and computes detect and mitigate times. Analysis looks for the contributing factors that let the failure happen rather than a person to blame, and action items come out specific, owned, dated and ticketed.
- name
postmortems - size173 lines · ≈1,800 tokens
- files1
- licenseMIT
- updated
What Claude sees before loading it
This description is the only part of the skill that sits in context all the time. Claude reads it to decide when to load the full playbook below.
description: Writes blameless incident postmortems — quantified customer impact, a UTC timeline rebuilt from alerts, chat, deploys, and dashboards, detection and response metrics, contributing factors instead of a single root cause, where the team got lucky, and action items with owners, due dates, and tickets. Use after an outage, incident, data loss, security event, or near-miss, when drafting an incident review or RCA, or when reviewing a postmortem that blames people or has vague actions.Try asking
- Write the postmortem for yesterday's checkout outage from this incident channel export
- Review this postmortem draft. It feels like it blames the engineer who deployed
- Turn our incident notes into action items with owners that will actually get done
Use it when
- After an outage, degradation, or data loss incident
- Writing up a security event or a notable near-miss
- A draft postmortem blames people or has vague actions
- Preparing for an incident review meeting
Skip it when
- The incident is still ongoing, use incident-response first
- You need step-by-step operational procedures for alerts, use runbooks instead
How to check the result
Every timeline entry cites a source, impact is expressed in numbers, no factor names a person as the cause, and each action item has one owner, a due date and a ticket.
The common mistake it prevents
Stopping the analysis at the triggering deploy or 'human error', which leaves the missing safeguards that let it reach production unaddressed.
A postmortem is done when someone outside the team understands what happened, how customers were affected (with numbers), why the system allowed it, and which specific, owned, dated changes will make a repeat less likely or less harmful. It names systems and decisions, never culprits.
Ground rules
- Blameless, not accountability-free: describe actions and the context that made them reasonable at the time. People acted on the information and tools they had.
- Facts first, with sources. Every timeline entry cites where it came from (alert, chat message link, deploy log, graph).
- Times in UTC, 24-hour, with the date on the first entry of each day.
- Contributing factors, plural. Complex failures rarely have one root cause; “human error” is never a root cause, it is a symptom of a system that allowed it.
- Fewer, stronger action items beat a long wish list. Each one has an owner, due date, and ticket.
- Draft within 3–5 business days while memory and logs are fresh; review in a meeting.
When to write one
Customer-facing outage or degradation above your severity threshold (commonly SEV1/SEV2), any data loss or corruption, security incidents, missed SLO error budget, on-call escalations that took more than an hour, and notable near-misses (an incident that almost happened is cheap tuition).
Workflow
- [ ] 1. Collect sources: alerts, incident channel, deploys, dashboards, tickets, status page
- [ ] 2. Build the timeline (detection → mitigation → resolution)
- [ ] 3. Quantify impact
- [ ] 4. Compute response metrics
- [ ] 5. Analyze contributing factors
- [ ] 6. Write what went well, what went poorly, where we got lucky
- [ ] 7. Define action items with owners, dates, tickets
- [ ] 8. Review meeting; publish; track actions to closure1–2. Timeline
# deploys and config changes in the window
git log --since="2026-10-14 13:00" --until="2026-10-14 17:00" --pretty='%h %ad %an %s' --date=iso-strict
gh run list --created "2026-10-14" --limit 50 --json name,headSha,createdAt,conclusionPull alert history from the paging tool, export the incident channel, and screenshot key graphs (link the dashboard with the time range in the URL).
| Time (UTC) | Event | Source |
|---|---|---|
| 2026-10-14 14:02 | Deploy 4f2c1a rolls out to 100%, adds index on `orders(created_at)` | deploy log |
| 14:06 | p95 checkout latency rises from 300 ms to 4.2 s | APM graph |
| 14:11 | Alert "checkout error rate > 2%" pages on-call (Priya) | PagerDuty |
| 14:19 | Incident declared SEV2; IC: Marco | #inc-2291 |
| 14:31 | Hypothesis: lock contention from index build; confirmed via `pg_stat_activity` | #inc-2291 |
| 14:38 | Index build cancelled; latency recovering | DB console |
| 14:44 | Error rate below 0.1%; mitigated | APM |
| 15:30 | Index recreated with CONCURRENTLY off-peak; resolved | deploy log |Mark the key moments: start of impact, detection, response start, mitigation, resolution.
3. Impact (numbers, not adjectives)
- Duration of customer impact: 38 min (14:06–14:44 UTC)
- Checkout requests failed: 9,412 of 61,030 (15.4%)
- Estimated lost orders: ~1,100 (≈ $48k GMV); 214 customers retried successfully later
- SLO: consumed 61% of the monthly error budget for checkout availability
- Support: 87 tickets; status page posted at 14:25
- Data: no data loss or corruption (verified by order reconciliation job)4. Response metrics
| Metric | Value | Note |
|---|---|---|
| Time to detect (impact → alert) | 5 min | |
| Time to acknowledge | 2 min | |
| Time to mitigate (impact → customer recovery) | 38 min | |
| Time to resolve | 1 h 24 min | |
| Detected by | Automated alert / customer / employee |
5. Contributing factors
Ask “what made this possible?” and “what made it worse or longer?” across categories:
| Category | Example finding |
|---|---|
| Change | Migration added a non-concurrent index on a 90M-row table |
| Safeguards | Migration linter does not flag CREATE INDEX without CONCURRENTLY |
| Testing | Staging table has 40k rows; lock time not representative |
| Detection | No alert on lock wait time; error-rate alert fired 5 min after impact |
| Response | Runbook for DB contention linked to a deleted dashboard |
| Process | Migrations auto-run at deploy time with no size-based review |
“Five whys” is a useful prompt but stop when you reach organizational or design factors you can change; do not stop at a person.
Blameless rewrites:
| Before | After |
|---|---|
| “Alex ran a bad migration.” | “The migration created an index without CONCURRENTLY. Nothing in review or CI flags this pattern, and staging data volume did not reveal the lock.” |
| “On-call was slow to respond.” | “The page reached on-call 5 minutes after impact began; the runbook link pointed to a removed dashboard, adding ~8 minutes to diagnosis.” |
| “Human error.” | “The deploy tool allows production config edits without a diff preview.” |
6. Went well / poorly / lucky
- Went well: what to keep (fast IC handoff, clear status updates).
- Went poorly: friction in detection and response.
- Where we got lucky: conditions that limited damage by chance (incident happened outside peak; an engineer happened to know the DB internals). Lucky items often become action items.
7. Action items
| ID | Action | Type | Owner | Due | Ticket | Priority |
|---|---|---|---|---|---|---|
| A1 | Add migration lint rule failing on CREATE INDEX without CONCURRENTLY on tables > 1M rows | Prevent | Dana | 2026-10-28 | PLAT-812 | P1 |
| A2 | Alert on Postgres lock wait > 5 s for 1 min | Detect | Priya | 2026-10-24 | OBS-221 | P1 |
| A3 | Fix DB contention runbook links; add runbook link check to CI | Mitigate | Marco | 2026-10-31 | OPS-90 | P2 |
Rules: action verbs, specific and verifiable, sized to finish in weeks not quarters (split large ones), one owner (a person, not a team). “Be more careful” and “improve monitoring” are not actions.
8. Review and follow-through
- 30–60 minute review with responders and owners of affected systems; walk the timeline, challenge factors, agree on actions.
- Publish where the org can find it; link from the incident ticket.
- Track action items in the normal backlog with a postmortem label; review open items weekly until closed.
Gotchas
- Writing from memory without sources produces confident but wrong timelines.
- Stopping at the trigger (the deploy) misses why the system was fragile to it.
- Overlong action lists where nothing ships; prioritize the top 3–5.
- Customer-facing summaries are a different document: shorter, no internal names, focused on impact and remediation.
- Sensitive details (security specifics, customer names) may need a restricted version.
Output contract
# Postmortem: <short title> (<YYYY-MM-DD>, SEV<n>)
Status: Draft | In review | Final Author: Incident commander: Review date:
## Summary
<3–4 sentences: what happened, impact, duration, main contributing factors, status>
## Impact
## Timeline (UTC)
## Response metrics
## Contributing factors
## What went well
## What went poorly
## Where we got lucky
## Action items
## Supporting material (graphs, links, chat export)About this skill
Written and maintained by the Claude Skills editors to the same editorial standard as every skill in the directory: a selective trigger, a real workflow, known pitfalls and a verification step. First published , last updated . MIT licensed.