aplaceforallmystuff/minervia-starter-kit/lessons-learned

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

1. Define the incident factually
2. Build a timeline
3. Find root cause with 5 Whys
4. Identify contributing factors
5. Implement fixes (don't just recommend them)
6. 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

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)

1. Why did [incident] happen?

→ Because [immediate cause]

1. Why did [immediate cause] happen?

→ Because [deeper cause]

1. Why did [deeper cause] happen?

→ Because [systemic issue]

1. Why did [systemic issue] exist?

→ Because [process gap]

1. Why did [process gap] exist?

→ Because [root cause]

Root Cause: [The fundamental issue to address]

Phase 4: Contributing Factors

Phase 5: Fix Classification

Phase 6: Fix Implementation

Don't just recommend fixes—implement them.

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

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