81 lines
3.0 KiB
Markdown
81 lines
3.0 KiB
Markdown
# LESSONS LEARNED - Critical Mistakes & Fixes
|
|
|
|
## Session: Feb 25, 2026 - Research Workflow & Automation Fixes
|
|
|
|
### **Lesson 1: Never Assume Workflows Are Complete**
|
|
**Mistake:** Research skill appeared to work but was missing critical deliverables (implementation plans, correct sprints, document verification).
|
|
|
|
**Root Cause:** Only tested individual components, not end-to-end workflow.
|
|
|
|
**Prevention:** Always run complete integration tests before marking features as working. Verify ALL deliverables exist and are correct.
|
|
|
|
**Impact:** Multiple broken research sessions, wasted time debugging.
|
|
|
|
---
|
|
|
|
### **Lesson 2: Documentation Must Match Implementation**
|
|
**Mistake:** Skills documented one workflow but agents followed different patterns.
|
|
|
|
**Root Cause:** Documentation not updated when code changed, leading to confusion.
|
|
|
|
**Prevention:** Documentation sync is part of completion checklist. Update docs in same PR as code changes.
|
|
|
|
**Impact:** Inconsistent behavior, user confusion about what agents should do.
|
|
|
|
---
|
|
|
|
### **Lesson 3: Automation Needs Authentication Strategies**
|
|
**Mistake:** Cron jobs tried to use direct API calls without proper auth setup.
|
|
|
|
**Root Cause:** Assumed existing auth would work for server-side automation.
|
|
|
|
**Prevention:** Design authentication for both user sessions AND automated processes from day one.
|
|
|
|
**Impact:** Broken automation, manual workarounds needed.
|
|
|
|
---
|
|
|
|
### **Lesson 4: External Services Need Fallbacks**
|
|
**Mistake:** Research workflow broke when X/Twitter blocked scraping.
|
|
|
|
**Root Cause:** Single point of failure with external API (Tavily).
|
|
|
|
**Prevention:** Always design fallback mechanisms for unreliable external services.
|
|
|
|
**Impact:** Research tasks failed silently, incomplete information gathering.
|
|
|
|
---
|
|
|
|
### **Lesson 5: Task Progress Needs Granular Tracking**
|
|
**Mistake:** Agent updates were too vague for resumption after failures.
|
|
|
|
**Root Cause:** Progress comments didn't include enough detail about what was done vs. remaining.
|
|
|
|
**Prevention:** Use checklist format with explicit completed/in-progress/remaining sections.
|
|
|
|
**Impact:** Agents couldn't resume work after interruptions, duplicate effort.
|
|
|
|
---
|
|
|
|
### **Lesson 6: API Architecture Matters**
|
|
**Mistake:** CLI scripts called database directly, breaking when API changed.
|
|
|
|
**Root Cause:** Mixed architecture (some API, some DB direct) created maintenance burden.
|
|
|
|
**Prevention:** Strict API-passthrough pattern. CLI only calls API, never DB. Business logic only in server.
|
|
|
|
**Impact:** Multiple breaking changes, inconsistent data access patterns.
|
|
|
|
---
|
|
|
|
### **General Rules Going Forward:**
|
|
|
|
1. **Test end-to-end** before claiming features work
|
|
2. **Update docs simultaneously** with code changes
|
|
3. **Design auth for automation** from the start
|
|
4. **Build fallback mechanisms** for external dependencies
|
|
5. **Use detailed progress tracking** for resumable work
|
|
6. **Maintain architectural consistency** (API-first, passthrough clients)
|
|
|
|
**Date Added:** February 25, 2026
|
|
**Session:** Research workflow debugging and automation fixes |