# 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