Systematic debugging using scientific method. Use when there are errors, exceptions, failing tests, or unexpected behavior. Trigger: "debug", "why does this fail", "there's a bug", "investigate error".
Activar cuando el usuario diga: "debug", "investiga", "por qué falla", "hay un error", "no funciona", "find the bug"
Seguir el proceso científico: hipótesis → experimento → conclusión. No adivinar.
Antes de tocar código, recopilar:
Generar mínimo 3 hipótesis, ordenadas por probabilidad:
H1 (más probable): [descripción] — Evidencia: [qué apunta a esto]
H2 (probable): [descripción] — Evidencia: [qué apunta a esto]
H3 (menos probable): [descripción] — Evidencia: [qué apunta a esto]
Antes de escribir código:
git bisect si aplicaPara cada hipótesis (de más a menos probable):
Técnicas de diagnóstico por categoría:
| Categoría | Técnica |
|---|---|
| Lógica | Print debugging, watch variables, assert early |
| Concurrencia | Logs con timestamps, detectar race conditions |
| Performance | Profiling, flamegraphs, medir antes y después |
| Red/API | Inspeccionar request/response raw, timeouts |
| Base de datos | Log queries, EXPLAIN ANALYZE, verificar índices |
| Memoria | Heap dumps, memory profiler, leak detection |
fix(scope): descripción del bug corregido## Debug Report — [descripción breve del bug]
### Evidencia Recolectada
- Error: `[mensaje exacto]`
- Reproducible: [siempre / intermitente / solo en X entorno]
- Primer ocurrencia: [cuando]
### Hipótesis
1. **[H1]** — Probabilidad: alta — [razonamiento]
2. **[H2]** — Probabilidad: media — [razonamiento]
### Experimentos Realizados
- H1: [experimento] → [resultado] → [confirmado/descartado]
### Causa Raíz
[Explicación de la causa raíz una vez encontrada]
### Fix Aplicado
[Descripción del cambio y por qué resuelve el problema]
### Test Agregado
[Test que previene regresión]
.claude/hooks/pre-tool-use/security-check.pymemory/patterns/known-bugs.mddocs/decisions/