# Systematic Debugging

> Debugging sistemático — proceso de cinco fases, encontrar la causa raíz antes de arreglar.

- Skill: `jantoniofc/systematic-debugging-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jantoniofc/systematic-debugging-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jantoniofc/systematic-debugging-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JantonioFC (https://skillmd.com/u/jantoniofc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jantoniofc/systematic-debugging-2

---


# 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