Skill · Observability
Incident Postmortem Writer
Turn incident notes, alerts, chat logs, deploy history, and traces into a blameless, evidence-backed postmortem with impact, timeline, contributing conditions, detection and response gaps, and owned corrective actions. Use after a production incident, failed deployment, security event, or near miss when the team needs a durable learning document rather than a root-cause guess.
User-invocablev1.0.0
Updated Aug 4, 2026npx agentscamp add skills/incident-postmortem-writerInstall to ~/.claude/skills/incident-postmortem-writer/SKILL.md
Builds a blameless postmortem from evidence: normalizes the timeline, quantifies customer and SLO impact, distinguishes trigger from contributing conditions, evaluates detection and mitigation, and writes corrective actions with owner, priority, due date, and verification. Unknowns remain labeled instead of becoming a confident single-root-cause story.
Write a learning document grounded in evidence. Preserve uncertainty and avoid blame, invented precision, and action items that cannot be verified.
Workflow
- Establish the incident window. Collect detection, start, mitigation, recovery, and full-resolution times. Normalize timestamps to one timezone while preserving source links.
- Build the factual timeline. Merge alerts, deploys, logs, traces, tickets, and responder notes. Separate observed facts from inference. Resolve contradictions or list them explicitly.
- Quantify impact. Record affected users, regions, tenants, requests, data, duration, revenue or operational impact, and SLO/error-budget consumption. State measurement gaps.
- Explain system behavior. Describe the trigger, contributing technical and organizational conditions, failed or absent safeguards, and why the impact propagated. Avoid stopping at the first human action or component failure.
- Evaluate detection and response. Explain what detected the incident, what should have, time to acknowledge and mitigate, which runbooks or tools helped, and where responders lacked information or safe controls.
- Record what went well. Preserve defenses, decisions, automation, and coordination worth repeating—not as praise filler, but as operational knowledge.
- Create corrective actions. Each action needs a specific change, owner, priority, due date, and verification method. Balance prevention, detection, containment, recovery, and learning; avoid “be more careful” and “add monitoring” without a defined signal.
- Review sensitive detail. Remove secrets and unnecessary personal data. Coordinate disclosure for security, legal, or customer-facing facts without erasing engineering evidence from the controlled internal record.
- Track closure. Link actions to tickets and define who verifies completion and effectiveness. A merged change is not complete until the intended risk reduction is tested.
WARNING
Do not convert an unknown into a root cause to make the document feel complete. Label uncertainty, preserve competing hypotheses, and assign an investigation action with evidence needed to resolve it.
Output
Create one Markdown postmortem containing:
- executive summary and quantified impact
- incident and response timeline with evidence links
- trigger, contributing conditions, and safeguard analysis
- detection, mitigation, recovery, and communication assessment
- what worked and what increased impact
- corrective-action table with owner, priority, due date, and verification
- open questions and explicitly labeled unknowns
- follow-up review date for action effectiveness
Frequently asked questions
- What makes a postmortem blameless?
- It explains how system design, information, incentives, tooling, and safeguards made each action reasonable at the time. Blameless does not mean consequence-free or vague; it replaces individual blame with specific system conditions and accountable improvements.
- Should a postmortem identify one root cause?
- Usually not. Incidents emerge from a trigger interacting with latent conditions and failed safeguards. A single root-cause label often hides the detection, rollback, capacity, testing, and coordination changes that would prevent recurrence.
Related
- 10 Best Claude Skills for DevOps and SREUse Claude skills for incidents, rollbacks, SLOs, alerts, dashboards, logs, traces, containers, CI, and safer releases.
- Runbook WriterWrite an operational runbook a half-asleep on-call engineer can execute at 3am — scoped to ONE alert, leading with how to confirm the problem, the copy-pasteable mitigation that stops user pain, then diagnosis, escalation, and verification. Use when an alert has no documented response, after an incident exposed a missing procedure, or when standing up on-call for a service.
- SLO DefinerTurn a vague reliability goal into concrete SLIs, SLOs, an error budget, and burn-rate alerts — service-level indicators measured at the user-facing boundary, targets over a rolling window, and a written policy for what happens when the budget runs out. Use when a service has no defined reliability target, when on-call is noisy and alert-fatigued, or before you commit to an SLA you can't measure.
- Distributed Tracing InstrumenterInstrument a service (or a chain of services) with OpenTelemetry so a single request can be followed end-to-end — context propagated across every hop including async/queue boundaries, spans at the boundaries that matter, deliberate trace-wide sampling, and trace_id stamped on log lines. Use when latency or failures span multiple services, when you have logs but can't reconstruct a request's full path, or when adopting OpenTelemetry.
- Alerting Rules TunerCut alert noise and make every page mean something — rewrite alerting rules to fire on user-felt symptoms (error rate, latency SLO burn, failed requests) instead of causes (high CPU, full disk), with duration windows and severity routing so only urgent, actionable conditions reach a human. Use when on-call is fatigued by low-value pages, when real incidents get missed in the noise, or when alerts fire on causes rather than impact.
- Incident ResponderUse this agent during a live production incident to restore service fast and learn from it — triage and severity, mitigation-first action (roll back, fail over, shed load), change correlation, status updates, and the blameless postmortem. Examples — an alert just fired and the API is 5xx-ing, a deploy broke checkout and you need to decide rollback vs. forward-fix, latency is climbing and the pager is going off, or you're writing the postmortem the morning after.