Lessons Learned: Structured Retrospective

Analyse incidents using a structured framework, identify root causes, and encode preventive measures directly into skills, guards, or documentation. The goal is systematic improvement, not blame.

When to Use

• After incidents, mistakes, rollbacks, or near-misses
• When the user says "what went wrong", "lessons learned", "post-mortem", "retrospective", or "how do we prevent this"
• After a stuck session where significant time was lost
• After a wrong-approach event (plan existed but execution diverged)

Process

Phase 1: Incident Definition

Capture the facts first, analysis later.

## Incident Summary

**What happened:** [Factual description]
**When:** [Date/time]
**Impact:** [What was affected, scope]
**Resolution:** [How it was fixed/rolled back]
**Time to resolution:** [How long to fix]

Phase 2: Timeline Reconstruction

Build a chronological sequence of events:

Key questions:

• What was the trigger?
• Where did the sequence 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]

2. Why did [immediate cause] happen?
   → Because [deeper cause]

3. Why did [deeper cause] happen?
   → Because [systemic issue]

4. Why did [systemic issue] exist?
   → Because [process gap]

5. Why did [process gap] exist?
   → Because [root cause]

Stop when you reach a cause that can be addressed by a concrete change to the system (skill, rule, hook, doc).

Phase 4: Contributing Factors

Identify all factors, not just the root cause:

Phase 5: Fix Classification

Classify each fix by type:

Phase 6: Fix Implementation

Implement fixes during the retrospective, not after. This is the critical difference from a report-only post-mortem.

For each fix:

1. Implement it (create/edit the file)
2. Record what was done:

Also record a [LEARN] tag in MEMORY.md for each key correction (per the learn-tags rule).

Phase 7: Verification

Define how to verify the fix works:

## Verification

**Test scenario:** [How to test the fix]
**Success criteria:** [What "fixed" looks like]
**Review date:** [When to check if fix is working — default: 2 weeks]

Output

Write the report to log/incidents/YYYY-MM-DD_short-description.md:

# Lessons Learned: [Incident Title]

**Date:** YYYY-MM-DD
**Severity:** [Low|Medium|High|Critical]
**Status:** [Resolved|Monitoring|Open]

## Incident Summary
[Brief description]

## Timeline
| Time | Action | Actor | 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]

Create log/incidents/ if it doesn't exist.

Common Incident Patterns

Anti-Patterns

Cross-References

• [LEARN] tags — record one-liner corrections in MEMORY.md (the quick complement to this skill)
• skill-extract — extract a full skill from a session (when the fix type is "Skill")
• ideas — if a fix is too large for this session, capture as an idea for later

Success Criteria

The retrospective is complete when:

• 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 (skill, rule, hook, doc)
• [LEARN] tags recorded in MEMORY.md
• Verification criteria defined
• Report written to log/incidents/