# LESSONS.md - Hybrid Protocol Lessons Learned

## Purpose
This file captures tactical learnings, insights, and immediate feedback from daily work. It's the "working memory" of the system - practical knowledge to inform future work.

## How to Use
1. **Add lessons as they happen** - don't wait
2. **Be specific and actionable** - what exactly did we learn?
3. **Categorize properly** - use tags and sections
4. **Reference related tasks** - connect to actual work
5. **Review regularly** - weekly retrospective

## Update Frequency
- **Continuous:** Add lessons as they occur
- **Daily:** Quick organization
- **Weekly:** Categorization and prioritization
- **Monthly:** Synthesis into SYSTEM-INTEL.md

## Structure

### Part 1: This Week's Lessons (Most Recent)
Fresh insights from current work.

### Part 2: Categorized Lessons
Organized by topic for easy reference.

### Part 3: Action Items
Lessons that require specific actions.

### Part 4: Archived Lessons
Historical lessons (moved after 90 days).

---

## Part 1: This Week's Lessons (Week of [YYYY-MM-DD])

### New This Week
*Add lessons here as they happen throughout the week*

#### [YYYY-MM-DD] Lesson Title
**From:** [Task/Person/Incident]
**Category:** [Process/Technical/People/Tool]
**Priority:** [High/Medium/Low]
**Tags:** #tag1 #tag2

**What happened:**
[Brief description of the situation]

**What we learned:**
- [Specific insight 1]
- [Specific insight 2]
- [Specific insight 3]

**Evidence/Data:**
- [Relevant data or examples]
- [Task reference if applicable]

**Implications:**
- [How this affects our work]
- [What might change]

**Action Required:**
- [ ] [Specific action if needed]
- [ ] [Another action if needed]

**Added by:** [Name/System]
**Date:** [YYYY-MM-DD]

---

## Part 2: Categorized Lessons

### Process Lessons
*Insights about how we work*

#### Estimation & Planning
- [ ] *No lessons yet - add as they occur*

#### Review & Approval
- [ ] *No lessons yet - add as they occur*

#### Communication
- [ ] *No lessons yet - add as they occur*

#### Workflow
- [ ] *No lessons yet - add as they occur*

### Technical Lessons
*Insights about technology, code, systems*

#### Tools & Platforms
- [ ] *No lessons yet - add as they occur*

#### Code Patterns
- [ ] *No lessons yet - add as they occur*

#### Performance
- [ ] *No lessons yet - add as they occur*

#### Security
- [ ] *No lessons yet - add as they occur*

### People Lessons
*Insights about collaboration, skills, behavior*

#### Collaboration
- [ ] *No lessons yet - add as they occur*

#### Skills & Training
- [ ] *No lessons yet - add as they occur*

#### Feedback & Growth
- [ ] *No lessons yet - add as they occur*

### Quality Lessons
*Insights about quality, testing, standards*

#### Testing
- [ ] *No lessons yet - add as they occur*

#### Documentation
- [ ] *No lessons yet - add as they occur*

#### Standards
- [ ] *No lessons yet - add as they occur*

### Tool Lessons
*Insights about specific tools we use*

#### [Tool Name]
- [ ] *No lessons yet - add as they occur*

#### [Another Tool]
- [ ] *No lessons yet - add as they occur*

---

## Part 3: Action Items from Lessons

### High Priority Actions
| Action | Source Lesson | Owner | Due Date | Status |
|--------|---------------|-------|----------|--------|
| [Action] | [Lesson reference] | [Owner] | [Date] | [Not Started/In Progress/Done] |

### Medium Priority Actions
| Action | Source Lesson | Owner | Due Date | Status |
|--------|---------------|-------|----------|--------|
| [Action] | [Lesson reference] | [Owner] | [Date] | [Not Started/In Progress/Done] |

### Low Priority Actions
| Action | Source Lesson | Owner | Due Date | Status |
|--------|---------------|-------|----------|--------|
| [Action] | [Lesson reference] | [Owner] | [Date] | [Not Started/In Progress/Done] |

---

## Part 4: Archived Lessons (Older than 90 days)

*Lessons moved here after they're no longer immediately relevant but should be kept for historical reference*

### [Month Year] Archive
- [ ] *No archived lessons yet*

---

## Lesson Template (Copy & Paste)

```
#### [YYYY-MM-DD] Lesson Title
**From:** [Task/Person/Incident]
**Category:** [Process/Technical/People/Tool/Quality]
**Priority:** [High/Medium/Low]
**Tags:** #tag1 #tag2 #tag3

**What happened:**
[Brief description of the situation - what actually occurred]

**What we learned:**
- [Specific, actionable insight 1]
- [Specific, actionable insight 2]
- [Specific, actionable insight 3]

**Evidence/Data:**
- [Relevant data, metrics, or examples]
- [Reference to task/incident if applicable]
- [Quotes or specific observations]

**Implications:**
- [How this affects current work]
- [What might need to change]
- [Who needs to know this]

**Action Required:**
- [ ] [Specific, actionable item 1]
- [ ] [Specific, actionable item 2]
- [ ] [Specific, actionable item 3]

**Added by:** [Your Name/System]
**Date:** [YYYY-MM-DD]
```

## How to Write Good Lessons

### Do:
- **Be specific:** "The review took 3 days because..." not "Reviews are slow"
- **Be actionable:** "We should add a checklist for X" not "X is problematic"
- **Include evidence:** Reference data, examples, or observations
- **Connect to work:** Link to specific tasks or incidents
- **Suggest solutions:** What should we do differently?

### Don't:
- **Be vague:** "Communication needs improvement"
- **Blame individuals:** "John always messes up estimates"
- **State the obvious:** "We should test our code"
- **Forget the context:** Why did this happen? When?
- **Ignore patterns:** Is this a one-time thing or recurring?

## Categories Explained

### Process
- Workflow improvements
- Estimation techniques
- Review processes
- Communication methods
- Meeting effectiveness

### Technical
- Code patterns that work/don't work
- Tool usage tips
- Performance optimizations
- Security practices
- Integration patterns

### People
- Collaboration techniques
- Feedback methods
- Skill development
- Team dynamics
- Remote work insights

### Tool
- Specific tool tips/tricks
- Configuration insights
- Integration lessons
- Alternative tools
- Automation opportunities

### Quality
- Testing strategies
- Documentation practices
- Code review insights
- Bug prevention
- Standards enforcement

## Tag System

### Priority Tags
- #priority-high - Requires immediate attention
- #priority-medium - Should be addressed soon
- #priority-low - Nice to have

### Topic Tags
- #estimation - Related to sizing/planning
- #review - Related to review process
- #communication - Related to information sharing
- #tool-[name] - Specific tool lessons
- #bug-prevention - Lessons about avoiding bugs
- #process-improvement - Workflow enhancements

### Status Tags
- #action-required - Needs specific action
- #investigating - Being looked into
- #resolved - Issue addressed
- #recurring - Happens repeatedly

## Weekly Retrospective Format

### Each Friday:
1. **Review new lessons** from the week (10 min)
2. **Categorize and tag** properly (5 min)
3. **Identify patterns** across lessons (10 min)
4. **Create action items** for key lessons (5 min)
5. **Update SYSTEM-INTEL.md** with significant insights (10 min)

### Questions to Ask:
1. What lessons keep repeating?
2. What's our biggest pain point this week?
3. What worked surprisingly well?
4. What should we stop/start/continue doing?
5. What one change would make the biggest difference?

## Integration with Other Files

### From INBOX/OUTBOX:
- When task completes, ask: "What did we learn?"
- Add lesson to LESSONS.md
- Reference task ID for context

### To SYSTEM-INTEL.md:
- Monthly: Identify patterns in lessons
- Extract strategic insights
- Update SYSTEM-INTEL.md Part 3 (Pattern Recognition)

### From REVIEW_WORKFLOW:
- Review feedback often contains lessons
- Capture rejection reasons as lessons
- Use to improve review checklist

## Success Metrics for Lessons

### Quantity:
- Target: 2-5 lessons per week
- Too few: Not learning enough
- Too many: Overwhelming, need prioritization

### Quality:
- % with specific actions: > 80%
- % with evidence/data: > 70%
- % leading to changes: > 50%

### Impact:
- Reduction in repeated issues
- Improvement in key metrics
- Participant satisfaction with learning

---

## Getting Started

### First Week:
1. Add at least one lesson from your work
2. Participate in first weekly retrospective
3. Review existing lessons for patterns

### Ongoing:
1. Make lesson-capture a habit
2. Reference lessons when planning work
3. Celebrate when lessons lead to improvements

**Remember:** Every mistake is a lesson waiting to be captured. Every success has insights worth sharing.