systematic-debugging

# Systematic Debugging ## Principio core Arreglos al azar desperdician tiempo y crean bugs nuevos. ``` SIN FIX SIN INVESTIGACIÓN DE ROOT CAUSE PRIMERO SIN INVESTIGACIÓN SIN RECALL DE MEMORIA PRIMERO ``` ## Las Cinco Fases ### Fase 0: Recall de Memoria (PRIMER PASO OBLIGATORIO) 1. **Extraer keywords del error** (tipo de error, componente, proyecto) 2. **`mem_search`** con esos keywords 3. **Revisar resultados:** - ¿Experiencia relevante encontrada? → Aplicar directamente, saltar a Fase 4 - ¿Match parcial? → Usar como punto de partida - ¿Nada? → Proceder a Fase 1, recordar grabar la solución después ### Fase 1: Investigación de Root Cause 1. **Leer mensajes de error completamente** — no saltear nada 2. **Reproducir consistentemente** — pasos exactos, siempre 3. **Revisar cambios recientes** — git diff, nuevas deps, cambios de config 4. **Trazar flujo de datos** — ¿de dónde viene el valor incorrecto? Rastrear hacia atrás ### Fase 2: Análisis de Patrón 1. **Encontrar ejemplos que funcionan** en el mismo codebase 2. **Comparar contra referencias** — leer completamente 3. **Identificar cada diferencia** entre lo que funciona y lo roto 4. **Entender dependencias** — settings, config, entorno, suposiciones ### Fase 3: Hipótesis y Testing 1. **Formar hipótesis única**: "Creo que X es el root cause porque Y" 2. **Testear mínimamente** — el cambio más pequeño posible, una variable a la vez 3. **Verificar antes de continuar** — ¿funcionó? → Fase 4. ¿No? → Nueva hipótesis ### Fase 4: Implementación 1. **Crear test case fallido** — reproducción mínima, automatizada si es posible 2. **Implementar fix único** — UN cambio, sin mejoras de paso 3. **Verificar fix** — test pasa, ningún otro test roto 4. **Si 3 fallos consecutivos en el mismo bloque de problema** → PARAR, cuestionar arquitectura, hablar con Juan antes de más intentos. (Fallos en bloques distintos se cuentan separadamente.) ## Red Flags — PARAR y seguir el proceso - "Fix rápido por ahora, investigar después" - "Probar cambiando X" - Proponer soluciones antes de trazar el flujo de datos - "Un intento más" (cuando ya se intentó 2+) **Todos significan: PARAR. Volver a Fase 1.** ## Quick Reference | Fase | Actividades clave | Criterio de éxito | |------|------------------|-------------------| | **0. Recall** | Extraer keywords, `mem_search` | Resumen de recall | | **1. Root Cause** | Leer errores, reproducir, evidencia | Entender QUÉ y POR QUÉ | | **2. Patrón** | Encontrar ejemplos que funcionan, comparar | Identificar diferencias | | **3. Hipótesis** | Formar teoría, testear mínimamente | Confirmada o nueva hipótesis | | **4. Implementación** | Crear test, fix, verificar | Bug resuelto, tests pasan | ## Después de resolver Grabar con `mem_save`: - Cuál fue el root cause - Cómo se encontró - Approach del fix - Cómo prevenir recurrencia