LEARNINGS.md - Mistakes & Lessons

Purpose: Append-only log of mistakes, bugs, and lessons learned. Review monthly.

2026-02-22: Memory Optimization Implementation

Lesson: BOOT.md vs BOOTSTRAP.md

Mistake: Initially confused about boot file naming. Reality: BOOTSTRAP.md is correct (one-time setup), BOOT.md is unrecognized. Fix: Verified only BOOTSTRAP.md exists, left it alone per AGENTS.md instructions.

Lesson: Skills Audit Required

Mistake: 58 skills loaded but many unused (iOS-specific skills when mainly doing web). Reality: Each unused skill burns tokens in system prompt. Fix: Documented active skills, archived unused ones to knowledge base.

2026-02-20: Mission Control Database Design

Lesson: Table Prefixes Critical

Mistake: Initially considered tables without project prefixes. Reality: All Vercel apps share one Supabase - collisions possible. Fix: Enforced <project>_<table> naming convention with underscores.

2026-02-22: Next.js Environment Variables on Vercel

Lesson: Read Env Vars Inside Request Handlers

Mistake: Used module-level non-null assertions (process.env.VAR!) for Supabase config in API routes. Reality: Environment variables may not be available at module load time in Vercel serverless functions. The non-null assertion hid the real issue. Fix: Move process.env.* reads inside the request handler function. Add explicit validation with clear error messages for missing variables. Impact: "Invalid API key" error was actually missing env var, not bad Supabase credentials.

Format Template

## YYYY-MM-DD: [Brief Title]

### Lesson: [What was learned]
**Mistake:** [What went wrong]
**Reality:** [What actually happened]
**Fix:** [How it was resolved]

1.8 KiB Raw Blame History