AgentAlley

Skills · Infrastructure & ops

Postmortem Writing

Unverified●30/40

Write effective blameless postmortems with root cause analysis, timelines, and action items. Use when conducting incident reviews, writing postmortem documents, or improving incident response processes.

Originally by wshobson · MIT

Claude Code◐PartialHas SKILL.md but declares no allowed-tools — Claude Code will ask for permission each time
Cursor◐PartialPlain prose you can paste in — but no Cursor rules file
Codex◐PartialPlain prose you can paste in — but no AGENTS.md
Gemini CLI◐PartialPlain prose you can paste in
Copilot◐PartialPlain prose you can paste in — but no Copilot instructions file
npx agentalley add postmortem-writing

This command does not work yet — the CLI is still being built. Until then, use Raw in the reader below to take the file.

Who is stuck, and on what

Write effective blameless postmortems with root cause analysis, timelines, and action items. Use when conducting incident reviews, writing postmortem documents, or improving incident response processes.

The whole source

No sign-in, no blur, nothing truncated
postmortem-writing/SKILL.md234 lines6.8 KBRawView on GitHub
Frontmatter — 2 properties
namepostmortem-writing
descriptionWrite effective blameless postmortems with root cause analysis, timelines, and action items. Use when conducting incident reviews, writing postmortem documents, or improving incident response processes.
1---
2name: postmortem-writing
3description: Write effective blameless postmortems with root cause analysis, timelines, and action items. Use when conducting incident reviews, writing postmortem documents, or improving incident response processes.
4---A5 — No allowed-tools declared — no way to tell what this skill may touch
5 
6# Postmortem Writing
7 
8Comprehensive guide to writing effective, blameless postmortems that drive organizational learning and prevent incident recurrence.
9 
10## When to Use This Skill
11 
12- Conducting post-incident reviews
13- Writing postmortem documents
14- Facilitating blameless postmortem meetings
15- Identifying root causes and contributing factors
16- Creating actionable follow-up items
17- Building organizational learning culture
18 
19## Core Concepts
20 
21### 1. Blameless Culture
22 
23| Blame-Focused | Blameless |
24| ------------------------ | --------------------------------- |
25| "Who caused this?" | "What conditions allowed this?" |
26| "Someone made a mistake" | "The system allowed this mistake" |
27| Punish individuals | Improve systems |
28| Hide information | Share learnings |
29| Fear of speaking up | Psychological safety |
30 
31### 2. Postmortem Triggers
32 
33- SEV1 or SEV2 incidents
34- Customer-facing outages > 15 minutes
35- Data loss or security incidents
36- Near-misses that could have been severe
37- Novel failure modes
38- Incidents requiring unusual intervention
39 
40## Quick Start
41 
42### Postmortem Timeline
43 
44```
45Day 0: Incident occurs
46Day 1-2: Draft postmortem document
47Day 3-5: Postmortem meeting
48Day 5-7: Finalize document, create tickets
49Week 2+: Action item completion
50Quarterly: Review patterns across incidents
51```
52 
53## Templates and detailed worked examples
54 
55Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.
56 
57## References
58- [Connection Pool Best Practices](internal-wiki/connection-pools)
59- [Deployment Runbook](internal-wiki/deployment-runbook)
60```
61 
62### Template 2: 5 Whys Analysis
63 
64```markdown
65# 5 Whys Analysis: [Incident]
66 
67## Problem Statement
68 
69Payment service experienced 47-minute outage due to database connection exhaustion.
70 
71## Analysis
72 
73### Why #1: Why did the service fail?
74 
75**Answer**: Database connections were exhausted, causing all new requests to fail.
76 
77**Evidence**: Metrics showed connection count at 100/100 (max), with 500+ pending requests.
78 
79---
80 
81### Why #2: Why were database connections exhausted?
82 
83**Answer**: Each incoming request opened a new database connection instead of using the connection pool.
84 
85**Evidence**: Code diff shows direct `DriverManager.getConnection()` instead of pooled `DataSource`.
86 
87---
88 
89### Why #3: Why did the code bypass the connection pool?
90 
91**Answer**: A developer refactored the repository class and inadvertently changed the connection acquisition method.
92 
93**Evidence**: PR #1234 shows the change, made while fixing a different bug.
94 
95---
96 
97### Why #4: Why wasn't this caught in code review?
98 
99**Answer**: The reviewer focused on the functional change (the bug fix) and didn't notice the infrastructure change.
100 
101**Evidence**: Review comments only discuss business logic.
102 
103---
104 
105### Why #5: Why isn't there a safety net for this type of change?
106 
107**Answer**: We lack automated tests that verify connection pool behavior and lack documentation about our connection patterns.
108 
109**Evidence**: Test suite has no tests for connection handling; wiki has no article on database connections.
110 
111## Root Causes Identified
112 
1131. **Primary**: Missing automated tests for infrastructure behavior
1142. **Secondary**: Insufficient documentation of architectural patterns
1153. **Tertiary**: Code review checklist doesn't include infrastructure considerations
116 
117## Systemic Improvements
118 
119| Root Cause | Improvement | Type |
120| ------------- | --------------------------------- | ---------- |
121| Missing tests | Add infrastructure behavior tests | Prevention |
122| Missing docs | Document connection patterns | Prevention |
123| Review gaps | Update review checklist | Detection |
124| No canary | Implement canary deployments | Mitigation |
125```
126 
127### Template 3: Quick Postmortem (Minor Incidents)
128 
129```markdown
130# Quick Postmortem: [Brief Title]
131 
132**Date**: 2024-01-15 | **Duration**: 12 min | **Severity**: SEV3
133 
134## What Happened
135 
136API latency spiked to 5s due to cache miss storm after cache flush.
137 
138## Timeline
139 
140- 10:00 - Cache flush initiated for config update
141- 10:02 - Latency alerts fire
142- 10:05 - Identified as cache miss storm
143- 10:08 - Enabled cache warming
144- 10:12 - Latency normalized
145 
146## Root Cause
147 
148Full cache flush for minor config update caused thundering herd.
149 
150## Fix
151 
152- Immediate: Enabled cache warming
153- Long-term: Implement partial cache invalidation (ENG-999)
154 
155## Lessons
156 
157Don't full-flush cache in production; use targeted invalidation.
158```
159 
160## Facilitation Guide
161 
162### Running a Postmortem Meeting
163 
164```markdown
165## Meeting Structure (60 minutes)
166 
167### 1. Opening (5 min)
168 
169- Remind everyone of blameless culture
170- "We're here to learn, not to blame"
171- Review meeting norms
172 
173### 2. Timeline Review (15 min)
174 
175- Walk through events chronologically
176- Ask clarifying questions
177- Identify gaps in timeline
178 
179### 3. Analysis Discussion (20 min)
180 
181- What failed?
182- Why did it fail?
183- What conditions allowed this?
184- What would have prevented it?
185 
186### 4. Action Items (15 min)
187 
188- Brainstorm improvements
189- Prioritize by impact and effort
190- Assign owners and due dates
191 
192### 5. Closing (5 min)
193 
194- Summarize key learnings
195- Confirm action item owners
196- Schedule follow-up if needed
197 
198## Facilitation Tips
199 
200- Keep discussion on track
201- Redirect blame to systems
202- Encourage quiet participants
203- Document dissenting views
204- Time-box tangents
205```
206 
207## Anti-Patterns to Avoid
208 
209| Anti-Pattern | Problem | Better Approach |
210| ----------------------- | -------------------------- | ------------------------------- |
211| **Blame game** | Shuts down learning | Focus on systems |
212| **Shallow analysis** | Doesn't prevent recurrence | Ask "why" 5 times |
213| **No action items** | Waste of time | Always have concrete next steps |
214| **Unrealistic actions** | Never completed | Scope to achievable tasks |
215| **No follow-up** | Actions forgotten | Track in ticketing system |
216 
217## Best Practices
218 
219### Do's
220 
221- **Start immediately** - Memory fades fast
222- **Be specific** - Exact times, exact errors
223- **Include graphs** - Visual evidence
224- **Assign owners** - No orphan action items
225- **Share widely** - Organizational learning
226 
227### Don'ts
228 
229- **Don't name and shame** - Ever
230- **Don't skip small incidents** - They reveal patterns
231- **Don't make it a blame doc** - That kills learning
232- **Don't create busywork** - Actions should be meaningful
233- **Don't skip follow-up** - Verify actions completed
234 

Reviews

Installed this one?Write the first review and take the Trailblazer badge.

Reviews only open after a real install, so this is empty — and we leave it empty rather than invent one.

Alternatives

Also in Infrastructure & ops
Paper Poster (HTML): measurement-gated poster generationDEFAULT poster pipeline — build an academic conference poster (ICML/NeurIPS/ICLR/CVPR/...) as a single HTML/CSS file with measurement-driven hard gates, real paper figures, a two-hue design-token system, and print-ready PDF via headless Chromium. Use when theInfrastructure & ops · MIT●····●36/40Brand Monitoring 📡Brand monitoring tool for tracking mentions across social media platforms. Monitor Reddit, Google News, YouTube, and DuckDuckGo for brand mentions. Includes sentiment analysis, trend tracking, crisis detection, and competitor comparison. No API key required foInfrastructure & ops · MIT◐····●34/40Spark Memory & Thermal OpsManage unified memory and thermals during long-running ML jobs on NVIDIA DGX Spark. Use when planning memory headroom for a training run on GB10, when a job OOMs on unified memory, or when monitoring temperature and power during multi-hour training.Infrastructure & ops · MIT◐····●32/40Secrets ManagementImplement secure secrets management for CI/CD pipelines using Vault, AWS Secrets Manager, or native platform solutions. Use when handling sensitive credentials, rotating secrets, or securing CI/CD environments.Infrastructure & ops · MIT◐····●32/40