aplaceforallmystuff Lessons Learned
Transform problems into systematic improvements through structured retrospective analysis.
Why This Matters
Mistakes repeat when we only fix symptoms. With structured retrospectives:
- Root causes get addressed, not just symptoms
- Fixes are encoded into the system (skills, guards, docs)
- Each problem makes the system stronger
- You never hear "we should have thought about that first"
Quick Start
- Define the incident factually
- Build a timeline
- Find root cause with 5 Whys
- Identify contributing factors
- Implement fixes (don't just recommend them)
- Define verification criteria
Process
Phase 1: Incident Definition
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]
Phase 2: Timeline Reconstruction
| Time | Action | Actor | Outcome |
|---|---|---|---|
| HH:MM | [What was done] | [Who] | [Result] |
Key questions:
- What was the trigger?
- Where did things diverge from expected?
- What was the point of no return?
Phase 3: Root Cause Analysis (5 Whys)
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]
Phase 4: Contributing Factors
| 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] |
Phase 5: Fix Classification
| 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 |
Phase 6: Fix Implementation
Don't just recommend fixes—implement them.
| Fix | Type | Location | Status |
|---|---|---|---|
| [Description] | Skill | [Path] | Created |
| [Description] | Doc | [Path] | Updated |
Phase 7: Verification
**Test scenario:** [How to test the fix]
**Success criteria:** [What "fixed" looks like]
**Review date:** [When to check if working]
Output Template
# 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
Common Patterns
Premature Action
Symptom: Action taken before approval Fix: Add explicit approval gate
Sequence Error
Symptom: Steps in wrong order Fix: Encode sequence with numbered steps
Missing Validation
Symptom: Bad data passed through Fix: Add validation checkpoint
Context Carryover
Symptom: Assumptions from prior session caused issue Fix: Add explicit context verification
Scope Creep
Symptom: Did more than requested Fix: Ask clarifying questions before expanding
Anti-Patterns
| 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 |
Success Criteria
- Incident clearly defined with timeline
- Root cause identified (not just symptoms)
- Contributing factors documented
- At least one fix implemented (not just recommended)
- Fix encoded in appropriate location
- Verification criteria defined