3.0 KiB
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:
- Test end-to-end before claiming features work
- Update docs simultaneously with code changes
- Design auth for automation from the start
- Build fallback mechanisms for external dependencies
- Use detailed progress tracking for resumable work
- Maintain architectural consistency (API-first, passthrough clients)
Date Added: February 25, 2026 Session: Research workflow debugging and automation fixes