# Lessons Learned

# Lessons Learned: {{PROJECT_NAME}}

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

<!-- GUIDANCE: Lessons learned are the accumulated wisdom from a project, sprint, or phase.
They only have value if they change future behavior. At ALAI, every lesson must produce
either a system fix (hook/tool/rule) or a knowledge base contribution.
"Lessons learned without behavior change is not learning." — Alem, 2026-02-13 (ZAKON #0) -->

## 1. Session Metadata

| Field | Value |
|-------|-------|
| **Session Type** | Sprint Retrospective / Phase Review / Post-Mortem / Project Close |
| **Project** | {{PROJECT_NAME}} |
| **Phase / Sprint** | {{PHASE_OR_SPRINT}} |
| **Period Covered** | {{START_DATE}} – {{END_DATE}} |
| **Facilitator** | {{NAME}} |
| **Participants** | {{LIST_OF_PARTICIPANTS}} |
| **Date of Session** | {{DATE}} |
| **Duration** | {{DURATION}} |

---

## 2. What Went Well (Keep Doing)

<!-- GUIDANCE: Identify specific practices, decisions, and behaviors that contributed to positive outcomes.
Be specific — "communication was good" is not useful. "Daily written standups surfaced blockers
within 24 hours, preventing a 1-week delay" is useful.
Ask: What specifically worked? Why did it work? How do we ensure we keep doing it? -->

| # | What Went Well | Why It Worked | How to Preserve | Category |
|---|---------------|--------------|-----------------|----------|
| KD-01 | {{DESCRIPTION}} | {{ROOT_CAUSE_OF_SUCCESS}} | {{PROCESS/RULE/HABIT}} | Process / Technical / Communication / Tools |
| KD-02 | | | | |
| KD-03 | | | | |
| KD-04 | | | | |
| KD-05 | | | | |

### Highlights

<!-- GUIDANCE: For 1-3 standout items, write a brief narrative explaining the win and its context. -->

**KD-01 Detail:**
{{EXTENDED_NARRATIVE_OF_WHAT_WORKED_AND_WHY}}

---

## 3. What Didn't Go Well (Stop Doing)

<!-- GUIDANCE: Be honest and specific. The goal is to identify root causes, not assign blame.
Every "what didn't work" entry must have an action item — otherwise it's just venting.
Use the 5 Whys if the root cause is not obvious.
Reference ZAKON #1: Every mistake must become a systemic fix. -->

| # | What Didn't Work | Root Cause | Impact (1-10) | Action Item | Owner | Deadline |
|---|-----------------|-----------|--------------|-------------|-------|----------|
| SD-01 | {{DESCRIPTION}} | {{ROOT_CAUSE}} | {{IMPACT}} | {{SPECIFIC_ACTION}} | {{OWNER}} | {{DATE}} |
| SD-02 | | | | | | |
| SD-03 | | | | | | |
| SD-04 | | | | | | |

### Root Cause Analysis — Deep Dives

<!-- GUIDANCE: For high-impact items (score ≥ 7), document the full 5-Whys analysis. -->

#### SD-{{XX}}: {{ISSUE_TITLE}}

**Problem:** {{CLEAR_PROBLEM_STATEMENT}}

**5 Whys:**
1. Why did this happen? → {{ANSWER_1}}
2. Why did {{ANSWER_1}} happen? → {{ANSWER_2}}
3. Why did {{ANSWER_2}} happen? → {{ANSWER_3}}
4. Why did {{ANSWER_3}} happen? → {{ANSWER_4}}
5. Why did {{ANSWER_4}} happen? → {{ROOT_CAUSE}}

**Root Cause:** {{DEFINITIVE_ROOT_CAUSE}}
**Systemic Fix:** {{HOOK/TOOL/RULE/PROCESS_CHANGE}}
**Ljestvica Fikseva (ZAKON #1):** Hook > Tool > Rule > CLAUDE.md > Memory

---

## 4. What to Try Next (Start Doing)

<!-- GUIDANCE: Experiments and new practices to try in the next sprint/phase.
These are hypotheses — each should define how you'll measure if the experiment worked. -->

| # | What to Try | Expected Benefit | Hypothesis | Success Metric | Trial Period |
|---|------------|-----------------|------------|---------------|-------------|
| ST-01 | {{NEW_PRACTICE}} | {{EXPECTED_BENEFIT}} | If we do {{X}}, then {{Y}} will improve by {{Z}}% | {{MEASURABLE_METRIC}} | {{SPRINT_COUNT}} sprints |
| ST-02 | | | | | |
| ST-03 | | | | | |

---

## 5. Key Findings by Category

<!-- GUIDANCE: Categorize findings to enable cross-project pattern analysis.
ALAI uses these categories across all projects for systematic improvement. -->

### 5.1 Technical Findings

| # | Finding | Impact | Recommendation |
|---|---------|--------|---------------|
| TF-01 | {{TECHNICAL_FINDING}} | {{HIGH/MEDIUM/LOW}} | {{RECOMMENDATION}} |
| TF-02 | | | |

**Technical Patterns Observed:**
- {{PATTERN_1}} — {{IMPLICATION_AND_RECOMMENDATION}}
- {{PATTERN_2}}

### 5.2 Process Findings

| # | Finding | Root Cause | Recommendation |
|---|---------|-----------|---------------|
| PF-01 | {{PROCESS_FINDING}} | {{ROOT_CAUSE}} | {{RECOMMENDATION}} |
| PF-02 | | | |

**Process Patterns Observed:**
- {{PATTERN}}

### 5.3 Communication Findings

| # | Finding | Stakeholder Impact | Recommendation |
|---|---------|-------------------|---------------|
| CF-01 | {{COMMUNICATION_FINDING}} | {{IMPACT}} | {{RECOMMENDATION}} |
| CF-02 | | | |

### 5.4 Tools & Infrastructure Findings

| # | Finding | Impact | Recommendation |
|---|---------|--------|---------------|
| IF-01 | {{TOOLING_FINDING}} | {{IMPACT}} | {{RECOMMENDATION}} |
| IF-02 | | | |

### 5.5 Team & Collaboration Findings

| # | Finding | Impact | Recommendation |
|---|---------|--------|---------------|
| TM-01 | {{TEAM_FINDING}} | {{IMPACT}} | {{RECOMMENDATION}} |

---

## 6. Action Items

<!-- GUIDANCE: Every retrospective produces action items. Action items without owners and deadlines
are wishes, not commitments. Each item is tracked until closed. -->

| # | Action Item | Category | Owner | Sprint / Deadline | Priority | Status |
|---|------------|----------|-------|-------------------|----------|--------|
| AI-01 | {{SPECIFIC_ACTIONABLE_ITEM}} | Process / Technical / Communication / Tools | {{OWNER}} | Sprint {{X}} | P1/P2/P3 | Open |
| AI-02 | | | | | | |
| AI-03 | | | | | | |
| AI-04 | | | | | | |
| AI-05 | | | | | | |

**Action Item Review:** At the START of next sprint planning, PM reviews status of all open action items.
Incomplete P1 items are escalated to John.

---

## 7. Metrics Comparison — Planned vs. Actual

<!-- GUIDANCE: Honest comparison of plan vs. reality builds estimation accuracy over time.
These numbers feed into future project estimates — be accurate, not optimistic. -->

### 7.1 Timeline

| Milestone | Planned | Actual | Variance | Root Cause (if significant) |
|-----------|---------|--------|----------|----------------------------|
| Requirements Complete | {{DATE}} | {{DATE}} | {{+/- DAYS}} | {{ROOT_CAUSE}} |
| Design Complete | | | | |
| MVP Release | | | | |
| UAT Complete | | | | |
| Launch | | | | |

**Timeline Accuracy:** {{ACTUAL_DURATION}} vs. planned {{PLANNED_DURATION}} ({{VARIANCE_PCT}}% {{over/under}})

### 7.2 Budget

| Category | Planned (NOK) | Actual (NOK) | Variance | Notes |
|----------|-------------|-------------|----------|-------|
| Development | {{AMOUNT}} | {{AMOUNT}} | {{+/-}} | |
| Design | | | | |
| Infrastructure | | | | |
| Testing | | | | |
| **Total** | **{{TOTAL}}** | **{{TOTAL}}** | **{{+/-}}** | |

**Budget Accuracy:** {{ACTUAL}} vs. planned {{PLANNED}} ({{VARIANCE_PCT}}% {{over/under}})

### 7.3 Quality

| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Test coverage | ≥ 80% | {{PCT}}% | {{✅/⚠️/❌}} |
| Critical bugs at launch | 0 | {{COUNT}} | {{✅/⚠️/❌}} |
| Post-launch bugs (30 days) | < 5 | {{COUNT}} | {{✅/⚠️/❌}} |
| Lighthouse performance score | ≥ 90 | {{SCORE}} | {{✅/⚠️/❌}} |
| Accessibility (WCAG AA violations) | 0 | {{COUNT}} | {{✅/⚠️/❌}} |

### 7.4 Velocity & Estimation

| Sprint | Estimated Points | Completed Points | Accuracy |
|--------|-----------------|-----------------|---------|
| Sprint 1 | {{ESTIMATE}} | {{ACTUAL}} | {{PCT}}% |
| Sprint 2 | | | |
| Sprint 3 | | | |
| **Average** | | | **{{AVG_PCT}}%** |

**Estimation Accuracy Notes:** {{PATTERNS_IN_OVER_UNDER_ESTIMATION}}

---

## 8. Recommendations for Future Projects

<!-- GUIDANCE: Distill the most important learnings into specific recommendations
that a future project team should apply from Day 1. Be actionable, not philosophical. -->

| # | Recommendation | Category | Confidence | Applicable When |
|---|---------------|----------|-----------|----------------|
| REC-01 | {{RECOMMENDATION}} | Technical / Process / Communication | High / Medium | {{WHEN_TO_APPLY}} |
| REC-02 | | | | |
| REC-03 | | | | |
| REC-04 | | | | |
| REC-05 | | | | |

### Top 3 Most Important Learnings

<!-- GUIDANCE: If a future PM reads only 3 things from this document, what should they be? -->

1. **{{LEARNING_1_TITLE}}:** {{EXPLANATION_AND_RECOMMENDATION}}

2. **{{LEARNING_2_TITLE}}:** {{EXPLANATION_AND_RECOMMENDATION}}

3. **{{LEARNING_3_TITLE}}:** {{EXPLANATION_AND_RECOMMENDATION}}

---

## 9. Knowledge Base Contribution

<!-- GUIDANCE: Lessons only have lasting value if they're captured in durable systems.
Per ZAKON #1: every significant finding should produce a system-level fix.
Document what was contributed to which system. -->

| Finding | Contribution Type | Target System | Status | Owner |
|---------|-----------------|--------------|--------|-------|
| {{FINDING}} | New rule / Updated tool / New hook / HiveMind entry / CLAUDE.md update | {{SYSTEM}} | Open / Done | {{OWNER}} |

**HiveMind entries added:**
- `node ~/system/agents/hivemind/hivemind.js post "{{KEY_LEARNING}}"` _(run this)_

**Rules updated:**
- `~/system/rules/{{RULE_FILE}}` — {{WHAT_WAS_ADDED}}

**Memory updated:**
- `~/.claude/projects/-Users-makinja/memory/{{MEMORY_FILE}}` — {{WHAT_WAS_ADDED}}

---

## Approval

| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Project Manager | | | |
| AI Director (John) | | | |
| Team | (retrospective agreement) | | |