Depuración sistemática
Principio central: encontrar la causa raíz antes de intentar arreglos. Un fix al síntoma es una falla de depuración.
Violar la letra de este proceso es violar su espíritu.
La ley de hierro
NINGÚN FIX SIN INVESTIGAR LA CAUSA RAÍZ PRIMERO
Si no se completó la Fase 1, no se pueden proponer fixes. No aplica solo a bugs "difíciles" — los bugs simples también tienen causa raíz, y el proceso es rápido para ellos.
Fase 1 — Investigación de la causa raíz
Antes de intentar CUALQUIER fix:
Leer los mensajes de error con cuidado. No pasar por encima de errores ni warnings. Suelen contener la solución exacta. Leer el stack trace completo. Anotar números de línea, rutas de archivo, códigos de error.
Reproducir de forma consistente. ¿Se puede disparar de forma confiable? ¿Cuáles son los pasos exactos? ¿Pasa siempre? Si no es reproducible → juntar más datos, no adivinar.
Revisar cambios recientes. ¿Qué cambió que pudiera causar esto? git diff, commits recientes, dependencias nuevas, cambios de config, diferencias de entorno.
Juntar evidencia en sistemas de varios componentes. Cuando el sistema tiene varias capas (CI → build → firma; API → servicio → base de datos), antes de proponer fixes, agregar instrumentación de diagnóstico: en cada límite entre componentes, loguear qué dato entra y qué dato sale, verificar que la config/entorno se propaga, revisar el estado en cada capa. Correr una vez para juntar evidencia de dónde se rompe. Después analizar la evidencia para identificar el componente que falla. Recién después investigar ese componente específico.
Trazar el flujo de datos hacia atrás. Cuando el error está profundo en el call stack: ¿de dónde sale el valor malo? ¿qué llamó a esto con el valor malo? Seguir trazando hacia arriba hasta encontrar el origen. Arreglar en el origen, no en el síntoma.
Fase 2 — Análisis de patrón
Encontrar el patrón antes de arreglar:
- Buscar ejemplos que funcionan. Localizar código similar que sí funciona en el mismo codebase. ¿Qué funciona que se parece a lo que está roto?
- Comparar contra la referencia. Si se está implementando un patrón, leer la implementación de referencia completa — cada línea, no en diagonal.
- Identificar diferencias. ¿Qué es distinto entre lo que funciona y lo que está roto? Listar cada diferencia, por chica que parezca. No asumir "eso no puede importar".
- Entender dependencias. ¿Qué otros componentes necesita esto? ¿Qué config, settings, entorno? ¿Qué asume?
Fase 3 — Hipótesis y prueba
Método científico:
- Formular UNA sola hipótesis. Enunciarla claro: "creo que X es la causa raíz porque Y". Escribirla. Ser específico, no vago.
- Probar mínimamente. El cambio más chico posible para probar la hipótesis. Una variable a la vez. No arreglar varias cosas de una.
- Verificar antes de continuar. ¿Funcionó? Sí → Fase 4. ¿No funcionó? Formular una hipótesis NUEVA. NO apilar más fixes encima.
- Cuando no se sabe: decir "no entiendo X". No fingir que se sabe. Preguntarle al humano o investigar más.
Fase 4 — Implementación
Arreglar la causa raíz, no el síntoma:
Crear un caso de prueba que falla. La reproducción más simple posible. Test automatizado si se puede; script de una vez si no hay framework. Tenerlo antes de arreglar. Ver tdd-workflow.
Implementar UN solo fix. Atacar la causa raíz identificada. Un cambio a la vez. Nada de "ya que estoy" ni refactors de paquete.
Verificar el fix. ¿Pasa el test ahora? ¿No se rompió ningún otro? ¿El problema está realmente resuelto? Ver tdd-workflow ("verificación antes de declarar trabajo completo").
Si el fix no funciona: PARAR. Contar cuántos fixes se intentaron. Si son menos de 3: volver a Fase 1 con la información nueva. Si son 3 o más: parar y cuestionar la arquitectura.
Si 3+ fixes fallaron — cuestionar la arquitectura. Patrón que indica un problema arquitectónico: cada fix revela un nuevo acoplamiento/estado compartido en otro lado; cada fix requiere "refactor masivo"; cada fix crea síntomas nuevos en otra parte. Parar y hablarlo con el humano antes de intentar más fixes. Esto no es una hipótesis fallida — es una arquitectura equivocada.
Señales de alerta — STOP y volver a Fase 1
Si Code se sorprende pensando:
- "Fix rápido por ahora, investigo después"
- "Probemos cambiar X a ver si funciona"
- "Es probablemente X, lo arreglo"
- "No entiendo del todo pero esto podría funcionar"
- "Acá están los problemas principales: [lista de fixes sin investigar]"
- Proponer soluciones antes de trazar el flujo de datos
- "Un intento más de fix" (con 2+ ya intentados)
- Cada fix revela un problema nuevo en otro lado
Todas significan: PARAR. Volver a Fase 1. Con 3+ fixes fallidos: cuestionar la arquitectura.
Señales del humano de que Code lo está haciendo mal
- "¿Eso no está pasando?" — Code asumió sin verificar.
- "¿Nos va a mostrar...?" — Code debió agregar instrumentación de evidencia.
- "Deja de adivinar" — Code está proponiendo fixes sin entender.
- "Piénsalo en serio / ultra-think" — cuestionar fundamentos, no síntomas.
Cuando aparezcan: PARAR. Volver a Fase 1.
Rationalizaciones comunes
| Excusa |
Realidad |
| "El problema es simple, no necesito proceso" |
Los problemas simples también tienen causa raíz. El proceso es rápido para bugs simples. |
| "Es una emergencia, no hay tiempo para proceso" |
La depuración sistemática es MÁS RÁPIDA que adivinar y probar en loop. |
| "Pruebo esto primero, después investigo" |
El primer fix marca el patrón. Hacerlo bien desde el principio. |
| "Escribo el test después de confirmar que el fix funciona" |
Los fixes sin test no se sostienen. El test primero prueba que el fix sirve. |
| "Varios fixes de una vez ahorra tiempo" |
No se puede aislar qué funcionó. Causa bugs nuevos. |
| "Veo el problema, lo arreglo" |
Ver el síntoma ≠ entender la causa raíz. |
Cuando el proceso revela "no hay causa raíz"
Si la investigación sistemática revela que el problema es genuinamente ambiental, dependiente de timing, o externo: (1) se completó el proceso, (2) documentar qué se investigó (en brain/trackers/bugs.md o el registro NOC si aplica), (3) implementar el manejo apropiado (retry, timeout, mensaje de error), (4) agregar logging para investigación futura. Pero: el 95% de los casos de "no hay causa raíz" son investigación incompleta.
Relación con otras skills
tdd-workflow — la Fase 4 escribe primero el test que falla (rojo) y recién después el fix. El alcance de ejecución sigue siendo quirúrgico: solo el test de la reproducción, no la suite entera (a menos que el humano lo pida).sequential-mode — depurar es una tarea a la vez. Nada de lanzar subagentes en paralelo para "probar varias hipótesis" sin aprobación explícita del humano.brain-adr — un bug que no se va a arreglar ahora se anota en brain/trackers/bugs.md; un hallazgo de riesgo mixto que surge durante la depuración va a un NOC.
Nota sobre plugins de flujo de trabajo
Si el proyecto tiene instalada una skill de "systematic-debugging" de un plugin genérico (por ejemplo Superpowers), esta skill la reemplaza con el mismo método de 4 fases, en español, e integrada con tdd-workflow (alcance quirúrgico) y el sistema brain/trackers/ para capturar bugs y hallazgos sin desviarse de la tarea actual.
1---2name: depuracion-sistematica3description: Disciplina de encontrar la causa raíz de un bug ANTES de intentar cualquier arreglo. Cuatro fases obligatorias — investigación, análisis de patrón, hipótesis, implementación — sin saltarse ninguna. Úsala siempre que aparezca un bug, un test que falla, comportamiento inesperado, un problema de rendimiento, o una falla de build/integración — antes de proponer o escribir un fix. Especialmente bajo presión de tiempo, cuando "un arreglo rápido" parece obvio, o cuando ya se intentaron varios fixes sin éxito.4---56# Depuración sistemática78**Principio central:** encontrar la causa raíz antes de intentar arreglos. Un fix al síntoma es una falla de depuración.910**Violar la letra de este proceso es violar su espíritu.**1112## La ley de hierro1314```15NINGÚN FIX SIN INVESTIGAR LA CAUSA RAÍZ PRIMERO16```1718Si no se completó la Fase 1, no se pueden proponer fixes. No aplica solo a bugs "difíciles" — los bugs simples también tienen causa raíz, y el proceso es rápido para ellos.1920## Fase 1 — Investigación de la causa raíz2122**Antes de intentar CUALQUIER fix:**23241. **Leer los mensajes de error con cuidado.** No pasar por encima de errores ni warnings. Suelen contener la solución exacta. Leer el stack trace completo. Anotar números de línea, rutas de archivo, códigos de error.25262. **Reproducir de forma consistente.** ¿Se puede disparar de forma confiable? ¿Cuáles son los pasos exactos? ¿Pasa siempre? Si no es reproducible → juntar más datos, no adivinar.27283. **Revisar cambios recientes.** ¿Qué cambió que pudiera causar esto? `git diff`, commits recientes, dependencias nuevas, cambios de config, diferencias de entorno.29304. **Juntar evidencia en sistemas de varios componentes.** Cuando el sistema tiene varias capas (CI → build → firma; API → servicio → base de datos), **antes de proponer fixes, agregar instrumentación de diagnóstico**: en cada límite entre componentes, loguear qué dato entra y qué dato sale, verificar que la config/entorno se propaga, revisar el estado en cada capa. Correr una vez para juntar evidencia de **dónde** se rompe. Después analizar la evidencia para identificar el componente que falla. Recién después investigar ese componente específico.31325. **Trazar el flujo de datos hacia atrás.** Cuando el error está profundo en el call stack: ¿de dónde sale el valor malo? ¿qué llamó a esto con el valor malo? Seguir trazando hacia arriba hasta encontrar el origen. **Arreglar en el origen, no en el síntoma.**3334## Fase 2 — Análisis de patrón3536**Encontrar el patrón antes de arreglar:**37381. **Buscar ejemplos que funcionan.** Localizar código similar que sí funciona en el mismo codebase. ¿Qué funciona que se parece a lo que está roto?392. **Comparar contra la referencia.** Si se está implementando un patrón, leer la implementación de referencia **completa** — cada línea, no en diagonal.403. **Identificar diferencias.** ¿Qué es distinto entre lo que funciona y lo que está roto? Listar cada diferencia, por chica que parezca. No asumir "eso no puede importar".414. **Entender dependencias.** ¿Qué otros componentes necesita esto? ¿Qué config, settings, entorno? ¿Qué asume?4243## Fase 3 — Hipótesis y prueba4445**Método científico:**46471. **Formular UNA sola hipótesis.** Enunciarla claro: "creo que X es la causa raíz porque Y". Escribirla. Ser específico, no vago.482. **Probar mínimamente.** El cambio más chico posible para probar la hipótesis. Una variable a la vez. No arreglar varias cosas de una.493. **Verificar antes de continuar.** ¿Funcionó? Sí → Fase 4. ¿No funcionó? Formular una hipótesis NUEVA. NO apilar más fixes encima.504. **Cuando no se sabe:** decir "no entiendo X". No fingir que se sabe. Preguntarle al humano o investigar más.5152## Fase 4 — Implementación5354**Arreglar la causa raíz, no el síntoma:**55561. **Crear un caso de prueba que falla.** La reproducción más simple posible. Test automatizado si se puede; script de una vez si no hay framework. Tenerlo **antes** de arreglar. Ver `tdd-workflow`.572. **Implementar UN solo fix.** Atacar la causa raíz identificada. Un cambio a la vez. Nada de "ya que estoy" ni refactors de paquete.583. **Verificar el fix.** ¿Pasa el test ahora? ¿No se rompió ningún otro? ¿El problema está realmente resuelto? Ver `tdd-workflow` ("verificación antes de declarar trabajo completo").594. **Si el fix no funciona:** PARAR. Contar cuántos fixes se intentaron. Si son menos de 3: volver a Fase 1 con la información nueva. **Si son 3 o más: parar y cuestionar la arquitectura.**60615. **Si 3+ fixes fallaron — cuestionar la arquitectura.** Patrón que indica un problema arquitectónico: cada fix revela un nuevo acoplamiento/estado compartido en otro lado; cada fix requiere "refactor masivo"; cada fix crea síntomas nuevos en otra parte. **Parar y hablarlo con el humano antes de intentar más fixes.** Esto no es una hipótesis fallida — es una arquitectura equivocada.6263## Señales de alerta — STOP y volver a Fase 16465Si Code se sorprende pensando:6667- "Fix rápido por ahora, investigo después"68- "Probemos cambiar X a ver si funciona"69- "Es probablemente X, lo arreglo"70- "No entiendo del todo pero esto podría funcionar"71- "Acá están los problemas principales: [lista de fixes sin investigar]"72- Proponer soluciones antes de trazar el flujo de datos73- "Un intento más de fix" (con 2+ ya intentados)74- Cada fix revela un problema nuevo en otro lado7576**Todas significan: PARAR. Volver a Fase 1.** Con 3+ fixes fallidos: cuestionar la arquitectura.7778## Señales del humano de que Code lo está haciendo mal7980- "¿Eso no está pasando?" — Code asumió sin verificar.81- "¿Nos va a mostrar...?" — Code debió agregar instrumentación de evidencia.82- "Deja de adivinar" — Code está proponiendo fixes sin entender.83- "Piénsalo en serio / ultra-think" — cuestionar fundamentos, no síntomas.8485**Cuando aparezcan: PARAR. Volver a Fase 1.**8687## Rationalizaciones comunes8889| Excusa | Realidad |90|---|---|91| "El problema es simple, no necesito proceso" | Los problemas simples también tienen causa raíz. El proceso es rápido para bugs simples. |92| "Es una emergencia, no hay tiempo para proceso" | La depuración sistemática es MÁS RÁPIDA que adivinar y probar en loop. |93| "Pruebo esto primero, después investigo" | El primer fix marca el patrón. Hacerlo bien desde el principio. |94| "Escribo el test después de confirmar que el fix funciona" | Los fixes sin test no se sostienen. El test primero prueba que el fix sirve. |95| "Varios fixes de una vez ahorra tiempo" | No se puede aislar qué funcionó. Causa bugs nuevos. |96| "Veo el problema, lo arreglo" | Ver el síntoma ≠ entender la causa raíz. |9798## Cuando el proceso revela "no hay causa raíz"99100Si la investigación sistemática revela que el problema es genuinamente ambiental, dependiente de timing, o externo: (1) se completó el proceso, (2) documentar qué se investigó (en `brain/trackers/bugs.md` o el registro `NOC` si aplica), (3) implementar el manejo apropiado (retry, timeout, mensaje de error), (4) agregar logging para investigación futura. Pero: el 95% de los casos de "no hay causa raíz" son investigación incompleta.101102## Relación con otras skills103104- **`tdd-workflow`** — la Fase 4 escribe primero el test que falla (rojo) y recién después el fix. El alcance de ejecución sigue siendo quirúrgico: solo el test de la reproducción, no la suite entera (a menos que el humano lo pida).105- **`sequential-mode`** — depurar es una tarea a la vez. Nada de lanzar subagentes en paralelo para "probar varias hipótesis" sin aprobación explícita del humano.106- **`brain-adr`** — un bug que no se va a arreglar ahora se anota en `brain/trackers/bugs.md`; un hallazgo de riesgo mixto que surge durante la depuración va a un `NOC`.107108## Nota sobre plugins de flujo de trabajo109110Si el proyecto tiene instalada una skill de "systematic-debugging" de un plugin genérico (por ejemplo Superpowers), esta skill la reemplaza con el mismo método de 4 fases, en español, e integrada con `tdd-workflow` (alcance quirúrgico) y el sistema `brain/trackers/` para capturar bugs y hallazgos sin desviarse de la tarea actual.
OrcaCl