# Lessons Learned Templates Create an entry in Lessons Learned database after every deploy (LEARN stage of pipeline). --- ## Standard Template ``` Title: [Feature/Bug name] - [Date] === WHAT WE TRIED === [Describe the approach taken] - Goal: [what we were trying to achieve] - Approach: [how we tried to achieve it] - Scope: [what was involved - files, systems, etc.] === WHAT WORKED === [Things that went well] - [Success 1] - [Success 2] - [Pattern to repeat] === WHAT DIDN'T WORK === [Things that failed or caused problems] - [Failure 1]: [why it failed] - [Failure 2]: [why it failed] - [Gotcha discovered] === WHAT TO DO DIFFERENTLY === [Improvements for next time] - [Change 1] - [Change 2] - [New pattern to adopt] === TIME SPENT === - Investigation: [X hours] - Planning: [X hours] - Building: [X hours] - Testing: [X hours] - Total: [X hours] === TAGS === [Category tags: Bug Fix, Feature, Refactor, Infrastructure, etc.] ``` --- ## Bug Fix Template ``` Title: [Bug name] Fix - [Date] === THE BUG === - Symptom: [what users saw] - Root cause: [why it happened] - Impact: [who was affected, how badly] === THE FIX === - Solution: [what we changed] - Files: [what files were modified] - Lines changed: [approximate count] === WHAT WORKED === - [Investigation approach that found the bug] - [Fix that resolved it] === WHAT DIDN'T WORK === - [Wrong assumptions we made] - [Red herrings we followed] === PREVENTION === - [How to prevent this bug class in future] - [Tests to add] - [Patterns to avoid] === TAGS === Bug Fix, [Area: Frontend/Backend/Database/etc.] ``` --- ## Feature Template ``` Title: [Feature name] - [Date] === THE FEATURE === - Purpose: [why we built it] - Users: [who benefits] - Success criteria: [how we know it worked] === IMPLEMENTATION === - Approach: [how we built it] - Key decisions: [important choices made] - Trade-offs: [what we sacrificed for what] === WHAT WORKED === - [Design decisions that paid off] - [Tools/patterns that helped] === WHAT DIDN'T WORK === - [Approaches we abandoned] - [Unexpected complications] === WHAT TO DO DIFFERENTLY === - [Better approaches discovered] - [Things to consider earlier next time] === METRICS === - Lines added: [count] - Files touched: [count] - Time to build: [hours] === TAGS === Feature, [Area: UI, API, Database, etc.] ``` --- ## Infrastructure Template ``` Title: [Infrastructure change] - [Date] === THE CHANGE === - What: [what infrastructure changed] - Why: [reason for the change] - Scope: [what systems affected] === IMPLEMENTATION === - Steps taken: [numbered list] - Rollback plan: [how to undo] === WHAT WORKED === - [Smooth parts of the change] - [Good practices followed] === WHAT DIDN'T WORK === - [Issues encountered] - [Unexpected downtime or problems] === MONITORING === - [How we verified success] - [Metrics to watch] === TAGS === Infrastructure, [System: VPS, Database, API, etc.] ``` --- ## Quick Entry (Minimal) For small changes that don't need full analysis: ``` Title: [Name] - [Date] What: [One sentence description] Worked: [What went well] Didn't work: [What didn't] Next time: [What to do differently] ``` --- ## Example Entries ### Bug Fix Example ``` Title: Call Transcription Fix - Jan 30, 2026 === THE BUG === - Symptom: Transcription not appearing during calls, AI summary empty - Root cause: startListening() was commented out in LiveCopilot.jsx - Impact: All users - no live transcription or AI assistance during calls === THE FIX === - Solution: Re-enabled Web Speech API transcription in LiveCopilot - Files: admin/src/components/LiveCopilot.jsx (lines 198-201) - Lines changed: 4 === WHAT WORKED === - Following the data flow (CallContext → LiveCopilot → CallOutcomeSheet) - Reading the actual code vs assuming based on comments === WHAT DIDN'T WORK === - Initial assumption that Twilio Media Streams handled everything - Didn't check if post-call transcription timing was compatible with UI === PREVENTION === - Don't comment out features without adding a clear "DISABLED" marker - Test transcription flow end-to-end after any call-related changes - Add automated test for transcription presence === TAGS === Bug Fix, Frontend, Calls, Transcription ``` ### Feature Example ``` Title: Clawdbot Scripts - Jan 30, 2026 === THE FEATURE === - Purpose: Automate system monitoring, briefs, and Slack-to-Notion sync - Users: Michael (receives briefs), CC (gets clean task queue) - Success criteria: Morning/evening briefs sent, Slack bugs auto-tracked === IMPLEMENTATION === - Approach: Bash scripts using curl to Notion/Telegram/Slack APIs - Key decisions: Use Claude Haiku for classification (fast, cheap) - Trade-offs: Bash vs Python (chose Bash for simplicity, may revisit) === WHAT WORKED === - Modular scripts (each does one thing) - Shared config.env for all credentials - Templates for consistent output === WHAT DIDN'T WORK === - Initial jq dependency (not available on all systems) - Python fallback needed for JSON parsing === WHAT TO DO DIFFERENTLY === - Consider Python from start for complex JSON handling - Add health check endpoint to Growth Engine API === METRICS === - Lines added: ~800 - Files created: 9 - Time to build: 2 hours === TAGS === Feature, Infrastructure, Automation, Clawdbot ``` --- ## Creating Entry via API ```bash # First, find or create Lessons Learned database ID LESSONS_DB="your-database-id" curl -X POST "https://api.notion.com/v1/pages" \ -H "Authorization: Bearer $NOTION_API_KEY" \ -H "Content-Type: application/json" \ -H "Notion-Version: 2022-06-28" \ -d '{ "parent": { "database_id": "'$LESSONS_DB'" }, "properties": { "Title": { "title": [{ "text": { "content": "Feature Name - Jan 30, 2026" } }] }, "Category": { "select": { "name": "Bug Fix" } }, "Date": { "date": { "start": "2026-01-30" } } }, "children": [ { "object": "block", "type": "heading_2", "heading_2": { "rich_text": [{ "type": "text", "text": { "content": "What We Tried" } }] } }, { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{ "type": "text", "text": { "content": "Description here..." } }] } } ] }' ```