postmortem-writing
Document root cause analysis for team learning. Blameless, actionable, preventive.
When & Why to Use This Skill
This Claude skill streamlines the creation of professional incident postmortems and Root Cause Analysis (RCA) reports. It empowers DevOps and engineering teams to document system failures using a structured, blameless approach that focuses on technical prevention rather than individual blame. By utilizing the '5 Whys' technique and actionable templates, it helps organizations build institutional knowledge and improve system reliability.
Use Cases
- Technical Outage Documentation: Create a comprehensive report following a service downtime to map out the incident timeline, identify the technical root cause, and quantify user impact.
- Blameless Culture Integration: Facilitate team learning sessions after a deployment failure by focusing on system gaps and process improvements rather than human error.
- Preventive Action Tracking: Generate structured action items with clear ownership and deadlines to ensure that monitoring gaps or missing validations identified during an incident are resolved.
- Stakeholder Communication: Summarize complex technical incidents into clear, honest postmortems that can be shared with stakeholders to demonstrate transparency and commitment to reliability.
| name | postmortem-writing |
|---|---|
| description | Document root cause analysis for team learning. Blameless, actionable, preventive. |
Postmortem Writing
Purpose
- Share learnings across team
- Prevent recurrence
- Build institutional knowledge
- Blameless culture
Template
# Postmortem: [Incident Title]
**Date:** YYYY-MM-DD
**Duration:** X hours
**Severity:** P1/P2/P3
**Author:** [Name]
## Summary
One paragraph describing what happened and impact.
## Timeline
- HH:MM - Event
- HH:MM - Detection
- HH:MM - Response started
- HH:MM - Mitigation
- HH:MM - Resolution
## Root Cause
Technical explanation of why this happened.
Use 5 Whys technique if helpful.
## Impact
- Users affected: X
- Revenue impact: $Y
- Data loss: None/Partial/Full
## What Went Well
- Detection was fast
- Team responded quickly
- Communication was clear
## What Went Wrong
- Monitoring gap
- Missing validation
- Unclear runbook
## Action Items
| Action | Owner | Due Date |
|--------|-------|----------|
| Add monitoring for X | @person | YYYY-MM-DD |
| Implement validation | @person | YYYY-MM-DD |
| Update runbook | @person | YYYY-MM-DD |
## Lessons Learned
Key takeaways for the team.
Principles
Blameless
- Focus on systems, not people
- "The system allowed X" not "Person did X"
- Assume good intentions
Actionable
- Every finding has an action item
- Actions have owners and dates
- Follow up on completion
Honest
- Don't minimize impact
- Include what went wrong
- Acknowledge gaps
5 Whys Example
- Why did the query fail? → Null user_id
- Why was user_id null? → Auth didn't set it
- Why didn't auth set it? → Token was expired
- Why wasn't expiry handled? → Missing check
- Why was check missing? → No test coverage
Root cause: Missing test for token expiry path