lessons-learned.md

# Lessons Learned

## General
- Verificar JWT `ref` para confirmar a que proyecto Supabase pertenece una key
- Windows paths necesitan comillas en bash: `cd "C:\path\with spaces"`
- Node.js eval con strings complejos: escribir a .js en vez de inline `-e`
- Suite project esta en `SUITE Completa`, no en carpetas standalone

## FastAPI + RAG
- SQLAlchemy: `metadata` es nombre reservado en DeclarativeBase. Usar `extra_metadata = Column("metadata", JSON)` o cambiar nombre
- OpenAI GPT-5.4+: usar `max_completion_tokens` en vez de `max_tokens`
- Gemini embeddings: el modelo es `gemini-embedding-001` (estable), NO `gemini-embedding-exp-03-07`
- FastAPI catch-all `/{path:path}` para SPA debe ir DESPUES de los API routers
- BOE: leyes muy antiguas (pre-1980) solo tienen PDF, no HTML. `clean_boe_html()` devuelve "Texto no disponible"

## Compactacion y Contexto (Claude Code internals)
- MEMORY.md se trunca a 200 lineas / 25KB - mantener como indice ligero
- El modelo da mas peso al contenido que viene AL FINAL del CLAUDE.md
- Cada cambio a CLAUDE.md o MEMORY.md rompe la prompt cache de toda la sesion
- `/compact` acepta instrucciones: `/compact Priorizar archivos editados y errores`
- Subagentes `Explore` reciben historial completo, no repetir contexto
- Subagente modelo `haiku` es mucho mas barato para tareas simples
- Auto-compact se dispara cuando quedan ~13K tokens libres del contexto
- Output de Bash se trunca a 30K chars, usar offset/limit en Read para archivos grandes

## Subagentes — Prevenir Desbordamiento de Contexto
- Subagentes que exploran libremente se quedan sin contexto en proyectos grandes (>30 archivos)
- SIEMPRE clasificar archivos en Phase 1 y pasar lista cerrada a cada agente
- SIEMPRE poner `max_turns: 20` (12 para tareas ligeras como deps) para evitar loops
- SIEMPRE decir al agente: "max 12 archivos full read, usa Grep para patrones, NO explores directorios"
- Usar `model: "sonnet"` en subagentes para velocidad, reservar opus para consolidacion
- Si un archivo tiene >300 lineas, decir al agente que lea solo las primeras 200
- Formato de output del agente: max 60 lineas, findings puros, sin relleno
- Truco clave: Grep patterns > Read files. Grep puede buscar en 100 archivos sin gastar contexto
- Output capado: Pedir formato estricto con max N lineas evita que el agente genere parrafos inútiles

## Internals Claude Code (source analysis)
- `runAgent.ts:756`: maxTurns viene de `maxTurns ?? agentDefinition.maxTurns` — param del tool sobreescribe
- `autoCompact.ts`: AUTOCOMPACT_BUFFER_TOKENS = 13000. Se dispara cuando tokens > (contextWindow - 13K)
- `agent.ts`: `getDefaultSubagentModel()` devuelve 'inherit' — sin especificar, hereda modelo padre
- Explore agent usa `model: 'haiku'` para usuarios externos (rápido y barato)
- `omitClaudeMd: true` en Explore/Plan — ahorra tokens quitando CLAUDE.md del contexto del agente
- `thinkingConfig: disabled` por defecto en subagentes regulares (no fork) — ahorra tokens
- El fork child tiene instrucciones: "output <500 words, start with Scope:, no tool calls between reports"
- `readFileState` del agente se clona del padre (fork) o se crea nuevo (regular) con cache limitada
- Agents de solo lectura (Explore) no reciben gitStatus — ahorro de hasta 40KB
- `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3` — tras 3 fallos seguidos, para de intentar compact

## Systematic Debugging Protocol (adaptado de obra/superpowers)

**Iron Law:** NO parchear sin root cause. Síntoma resuelto ≠ bug resuelto.

### Fase 1: Investigar (NO tocar código)
- Leer error COMPLETO (stack trace, no solo la última línea)
- Reproducir consistentemente
- `journalctl -u servicio -p err --since "10 min ago"` (filtrado, NO volcado)
- Cambios recientes: `git diff HEAD~3`, `.env` modificado, dependencias actualizadas
- Multi-componente (nginx → FastAPI → DB): instrumentar cada frontera

### Fase 2: Patrones
- Buscar código que SÍ funciona en el mismo proyecto (Grep, no exploración ciega)
- Comparar working vs broken: diff exacto, no "se parece"
- Entender dependencias completas (¿qué más usa esta función?)

### Fase 3: Hipótesis única
- Escribir UNA hipótesis concreta antes de tocar nada
- Cambiar UNA variable, verificar resultado
- Si falla: nueva hipótesis limpia, NO acumular fixes
- Admitir "no sé" > inventar solución

### Fase 4: Fix
- Fix mínimo al root cause
- Verificar con herramienta (curl, test, log) — no "debería funcionar"
- Si 3+ intentos fallan: PARAR. Es problema de arquitectura, no de implementación. Preguntar a Alex.

### Red Flags (reiniciar proceso si pienso esto):
- "Arreglo rápido por ahora, investigo después"
- "Cambio X a ver si funciona"
- "Varios cambios a la vez para ahorrar tiempo"
- "Un intento más" (tras 2+ fallos)