Structured retrospective for incidents and mistakes. Transforms problems into systematic improvements.
Transform problems into systematic improvements through structured retrospective analysis.
Mistakes repeat when we only fix symptoms. With structured retrospectives:
Capture facts first, analysis later.
## Incident Summary
**What happened:** [Factual description]
**When:** [Date/time]
**Impact:** [What was affected]
**Resolution:** [How it was fixed]
**Time to resolution:** [How long to fix]
| Time | Action | Actor | Outcome |
|---|---|---|---|
| HH:MM | [What was done] | [Who] | [Result] |
Key questions:
Why did [incident] happen? → Because [immediate cause]
Why did [immediate cause] happen? → Because [deeper cause]
Why did [deeper cause] happen? → Because [systemic issue]
Why did [systemic issue] exist? → Because [process gap]
Why did [process gap] exist? → Because [root cause]
Root Cause: [The fundamental issue to address]
| Category | Factor | Contribution |
|---|---|---|
| Process | Missing checkpoint | [How it contributed] |
| Communication | Unclear instructions | [How it contributed] |
| Technical | No validation | [How it contributed] |
| Context | Prior assumptions | [How it contributed] |
| Fix Type | When to Use | How to Encode |
|---|---|---|
| Skill | Recurring workflow needs structure | Create new skill |
| Guard | Action requires checkpoint | Add approval gate |
| Documentation | Knowledge gap | Update CLAUDE.md |
| Automation | Manual step forgotten | Create script/hook |
| Checklist | Multiple steps need verification | Add to skill |
Don't just recommend fixes—implement them.
| Fix | Type | Location | Status |
|---|---|---|---|
| [Description] | Skill | [Path] | Created |
| [Description] | Doc | [Path] | Updated |
**Test scenario:** [How to test the fix]
**Success criteria:** [What "fixed" looks like]
**Review date:** [When to check if working]
# Lessons Learned: [Incident Title]
**Date:** YYYY-MM-DD
**Severity:** Low | Medium | High | Critical
**Status:** Resolved | Monitoring | Open
## Incident Summary
[Brief description]
## Timeline
| Time | Action | Outcome |
## Root Cause
[The fundamental issue]
## Contributing Factors
- Factor 1
- Factor 2
## Fixes Implemented
| Fix | Type | Location | Status |
## Prevention
[How this prevents recurrence]
## Lessons
1. Key takeaway 1
2. Key takeaway 2
Symptom: Action taken before approval Fix: Add explicit approval gate
Symptom: Steps in wrong order Fix: Encode sequence with numbered steps
Symptom: Bad data passed through Fix: Add validation checkpoint
Symptom: Assumptions from prior session caused issue Fix: Add explicit context verification
Symptom: Did more than requested Fix: Ask clarifying questions before expanding
| Anti-Pattern | Problem | Instead |
|---|---|---|
| Blame assignment | Misses systemic issues | Focus on process |
| Single-cause thinking | Oversimplifies | Use 5 Whys |
| Recommendation without action | Lessons forgotten | Implement during retrospective |
| Vague fixes | "Be more careful" doesn't work | Encode specific changes |