systematic-debugging

name	systematic-debugging
description	Debugging sistemático — proceso de cinco fases, encontrar la causa raíz antes de arreglar.

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