systematic-debugging

Descripción general

¿Qué es systematic-debugging?

La skill systematic-debugging es un proceso estructurado en cuatro fases para depurar cualquier problema técnico: fallos de tests, bugs en producción, tests inestables (flaky), problemas de rendimiento, errores de build o fallos de integración.

En lugar de probar "un arreglo rápido" o editar código en la primera línea que muestra error, esta skill te obliga a investigar primero la causa raíz, y solo después diseñar y validar una solución duradera. Se basa en patrones prácticos y scripts de una base de código real, incluyendo helpers de espera basada en condiciones en TypeScript y un script Bash para localizar tests contaminantes.

Principio central y Ley de Hierro

El núcleo de systematic-debugging es sencillo:

• Principio central: Siempre encuentra la causa raíz antes de intentar correcciones. Las soluciones que solo tratan los síntomas son fracasos.

• Ley de Hierro:

  NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
  

Si no has completado la fase de investigación, no propones ni aplicas soluciones. Esto está diseñado para resistir la presión de tiempo, las conjeturas y las racionalizaciones del tipo "solo esta vez".

¿Para quién es esta skill?

systematic-debugging está dirigida a:

• Desarrolladores que trabajan en proyectos JavaScript/TypeScript y quieren correcciones fiables y reproducibles
• Ingenieros de test y QA que lidian con comportamientos inestables, timeouts aleatorios y estado de test contaminado
• Ingenieros de CI/CD y tooling que diagnostican fallos intermitentes de build o de integración
• Tech leads y revisores que quieren un proceso compartido y riguroso para el trabajo de depuración

Encaja especialmente bien si te importa más el análisis de causa raíz de alta calidad que parchear síntomas rápidamente.

¿Qué problemas resuelve?

Usa la skill systematic-debugging cuando necesites:

• Investigar fallos de tests que reaparecen una y otra vez tras varias "correcciones"
• Rastrear tests inestables (flaky) que dependen de timeouts arbitrarios o condiciones de carrera
• Entender comportamientos inesperados en lugar de simplemente silenciar errores
• Diagnosticar problemas de rendimiento o flujos lentos y sensibles al tiempo
• Depurar fallos de build o integración que solo aparecen en CI o bajo carga
• Encontrar qué test contamina el estado o deja archivos/directorios no deseados

El repositorio también incluye:

• condition-based-waiting.md y condition-based-waiting-example.ts para reemplazar setTimeout/sleep con espera robusta basada en condiciones en TypeScript
• defense-in-depth.md para añadir validación en múltiples capas de forma que ciertos bugs se vuelvan estructuralmente imposibles
• find-polluter.sh, un helper en Bash para localizar el test exacto que crea archivos o estado no deseado
• root-cause-tracing.md para rastrear errores a través de la cadena de llamadas hasta su origen real

¿Cuándo encaja bien systematic-debugging?

systematic-debugging es especialmente adecuado cuando:

• Estás bajo presión de tiempo y tentado a adivinar correcciones
• Un problema reaparece a pesar de múltiples intentos de arreglo
• Quieres un flujo de trabajo de depuración repetible para ti o tu equipo
• Estás estabilizando una suite de tests inestable o limpiando entornos de test contaminados

Puede ser menos apropiado si:

• Solo necesitas una generación de código rápida o un refactor puntual sin investigación
• Estás depurando fuera de los dominios técnicos descritos (por ejemplo, problemas de proceso no técnicos)
• No estás dispuesto a seguir un proceso por fases y prefieres la experimentación ad hoc

Si tu objetivo es "parche rápido ahora, ya lo reharemos luego", este proceso te parecerá estricto. Si tu objetivo es "arreglarlo una vez, correctamente", systematic-debugging está diseñado para ti.

Cómo usarla

Instalación y configuración

Para instalar la skill systematic-debugging en un agente o entorno de herramientas compatible, usa el comando npx proporcionado:

npx skills add https://github.com/obra/superpowers --skill systematic-debugging
``

Esto descarga la definición de la skill y sus documentos y scripts de soporte desde el repositorio `obra/superpowers`, bajo `skills/systematic-debugging`.

Después de la instalación:

1. Abre la skill `systematic-debugging` en la interfaz de tu agente o en tu UI de skills.
2. Asegúrate de que tu workspace tenga acceso al repositorio de tu proyecto, comandos de test y logs.
3. Confirma que puedes ver las guías markdown y scripts incluidos:
   - `SKILL.md`
   - `condition-based-waiting.md`
   - `defense-in-depth.md`
   - `root-cause-tracing.md`
   - `find-polluter.sh`

### Archivos y componentes clave
Para tomar decisiones de instalación y en el uso diario, estos archivos son los más importantes:

- **`SKILL.md`** – Define el proceso completo de depuración sistemática en cuatro fases, sus reglas y anti-patrones. Es el núcleo de la skill.
- **`condition-based-waiting.md`** – Explica cómo reemplazar timeouts arbitrarios en tests por espera basada en condiciones.
- **`condition-based-waiting-example.ts`** – Utilidades TypeScript como `waitForEvent` que implementan espera basada en condiciones sobre un `ThreadManager` y tipos de eventos.
- **`defense-in-depth.md`** – Muestra cómo aplicar validación en múltiples capas (punto de entrada, lógica de negocio, guardas de entorno, logging) para hacer que clases completas de bugs sean imposibles.
- **`find-polluter.sh`** – Script Bash que itera tests para encontrar qué archivo crea una ruta concreta (contaminación de estado).
- **`root-cause-tracing.md`** – Explica cómo rastrear un bug desde un stack trace hasta el disparador original y combinarlo con defense-in-depth.
- **`CREATION-LOG.md`** – Meta-log que explica cómo se extrajo y robusteció el marco; útil para entender la intención de diseño, menos crítico para el uso diario.

Para desarrolladores de **JavaScript/TypeScript**, el ejemplo en TypeScript y el script Bash suelen poder adaptarse directamente a tu proyecto.

### Ejecución del flujo de trabajo en cuatro fases
El proceso `systematic-debugging` se organiza en cuatro fases obligatorias (descritas en `SKILL.md`). Debes completar cada una antes de pasar a la siguiente.

#### Fase 1 – Investigación de causa raíz
Antes de tocar código, configuración o tests:

- **Lee con atención los mensajes de error y logs.**
  - No pases por encima de stack traces o warnings.
  - Registra números de línea, rutas de archivo y códigos de error.
- **Reproduce el problema de forma consistente.**
  - Establece un comando de reproducción mínimo y fiable.
  - Anota qué entradas y factores de entorno son necesarios.

En esta fase no propones ni implementas correcciones. El objetivo es entender: qué falla exactamente, dónde y bajo qué condiciones.

#### Fase 2 – Análisis de patrones
Una vez que la reproducción es fiable:

- Varía un factor cada vez (entradas, configuración, entorno) para ver qué cambia el resultado.
- Busca fronteras: valores o condiciones donde el comportamiento pasa de éxito a fallo.
- Usa logs, aserciones o instrumentación temporal para acotar la ruta que falla.

Al final de la Fase 2 deberías entender la forma del problema y las condiciones que lo disparan, no solo el mensaje de error final.

#### Fase 3 – Hipótesis y diseño
Ahora puedes formular una hipótesis:

- Declara claramente qué crees que es la causa raíz (flujo de datos, validación ausente, problema de tiempos, ruta incorrecta, etc.).
- Diseña un cambio **único y focalizado** que aborde esa causa raíz.
- Planifica cómo validarás la hipótesis usando tus pasos de reproducción.

Si la hipótesis falla, vuelves a la investigación/análisis en lugar de apilar más arreglos especulativos.

#### Fase 4 – Implementación y validación
Solo después de tener una hipótesis clara modificas código o configuración:

- Aplica el cambio más pequeño que aborde directamente la causa raíz.
- Ejecuta la reproducción mínima y luego la suite de tests completa.
- Usa la guía de:
  - `defense-in-depth.md` para añadir validación en múltiples capas
  - `root-cause-tracing.md` para asegurarte de que estás corrigiendo la fuente real
- Confirma que la corrección es robusta (por ejemplo, funciona bajo carga, en CI y para los edge cases identificados en la Fase 2).

Si la corrección no se comporta como esperabas, **no** acumules más cambios; vuelve a las fases anteriores.

### Uso de las utilidades de depuración en tu proyecto

#### Espera basada en condiciones para tests inestables (JavaScript/TypeScript)
Los tests inestables que dependen de `setTimeout` o `sleep` suelen romperse cuando las máquinas son más lentas, más rápidas o están bajo carga. `condition-based-waiting.md` y `condition-based-waiting-example.ts` muestran un patrón mejor: esperar a la condición que realmente te importa.

Migración típica:

```typescript
// ❌ Antes: adivinar tiempos
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();

// ✅ Después: esperar a la condición
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();

El archivo condition-based-waiting-example.ts incluye helpers como:

export function waitForEvent(
  threadManager: ThreadManager,
  threadId: string,
  eventType: LaceEventType,
  timeoutMs = 5000
): Promise<LaceEvent> { /* ... */ }

Adapta estos patrones a tu propia infraestructura de tests:

1. Copia o reimplementa las utilidades en los helpers de test de tu proyecto.
2. Reemplaza las llamadas arbitrarias a setTimeout/sleep por esperas basadas en condiciones.
3. Vuelve a ejecutar tu suite de tests para confirmar una reducción en la inestabilidad.

Esto apoya directamente el objetivo de systematic-debugging de eliminar causas raíz en lugar de ampliar timeouts al azar.

Encontrar tests contaminantes con find-polluter.sh

Si tus tests dejan archivos o directorios extra o contaminan de algún modo el estado, find-polluter.sh te ayuda a localizar el test exacto responsable.

Uso (desde la raíz de tu proyecto, ajustando los argumentos según sea necesario):

./find-polluter.sh <file_or_dir_to_check> <test_pattern>

# Example
./find-polluter.sh '.git' 'src/**/*.test.ts'

El script:

• Descubre archivos de test que coincidan con el patrón
• Los ejecuta uno por uno con npm test <file>
• Tras cada ejecución, comprueba si el archivo o directorio objetivo existe ahora
• Se detiene e informa del primer test que lo creó, junto con los comandos para volver a ejecutarlo e inspeccionarlo

Esto encaja en la Fase 1 y Fase 2 de systematic-debugging, proporcionando una forma fiable de reproducir y aislar la contaminación de estado.

Aplicar validación defense-in-depth

Cuando tu investigación revela un bug causado por datos inválidos o supuestos erróneos, defense-in-depth.md recomienda colocar validaciones en varias capas:

• Validación en el punto de entrada – Rechazar entradas obviamente inválidas en los límites (APIs, CLI, handlers de UI).
• Validación en la lógica de negocio – Asegurar que los datos tienen sentido para las operaciones específicas.
• Guardas de entorno – Evitar operaciones peligrosas en el entorno o ruta equivocados.
• Logging de diagnóstico – Proporcionar contexto útil si algo se cuela.

Por ejemplo, validando un argumento workingDirectory:

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... proceed
}

Usa estos patrones al implementar las correcciones de la Fase 4 para asegurarte de que el bug no pueda reaparecer fácilmente a través de otra ruta de código.

Cuándo no usar esta skill

Puede ser mejor omitir o posponer systematic-debugging si:

• Estás prototipando y aceptas conscientemente código desechable y bugs
• El problema es trivial y está completamente entendido (por ejemplo, un typo conocido detectado durante el desarrollo) y no justifica el rigor de las cuatro fases
• Solo necesitas las utilidades de ejemplo (como las esperas basadas en condiciones) y no el proceso completo

Incluso en estos casos, la Ley de Hierro es un buen recordatorio: si te descubres acumulando varias conjeturas, es momento de cambiar a systematic-debugging.

Preguntas frecuentes (FAQ)

¿Qué cambia systematic-debugging realmente en mi flujo de trabajo?

En lugar de saltar directamente del mensaje de error a editar código, systematic-debugging te obliga a pasar por investigación, análisis de patrones e hipótesis antes de implementar. En la práctica esto significa:

• Capturas una reproducción fiable antes de tocar código
• Varias las condiciones para entender el espacio del problema
• Escribes una corrección focalizada por cada hipótesis validada

El resultado son menos reverts, menos regresiones ocultas y un tiempo de depuración más predecible.

¿Cómo instalo la skill systematic-debugging?

Usa el comando npx skills:

npx skills add https://github.com/obra/superpowers --skill systematic-debugging

Después de instalarla, abre la skill en tu agente o directorio de skills y revisa SKILL.md para ver el proceso completo y los archivos markdown de soporte para patrones y ejemplos.

¿systematic-debugging sirve para depuración en JavaScript y TypeScript?

Sí. Aunque el marco en sí es agnóstico del lenguaje, el repositorio incluye utilidades concretas orientadas a JavaScript/TypeScript:

• condition-based-waiting-example.ts para espera basada en condiciones en tests
• Patrones en defense-in-depth.md y root-cause-tracing.md ilustrados con ejemplos en TypeScript
• find-polluter.sh, que asume npm test por defecto y funciona bien con runners de test típicos de JS/TS

Puedes adaptar estas utilidades a la estructura y tooling de tu proyecto.

¿Puedo usar systematic-debugging para automatizar la depuración de tests inestables?

Sí. Es uno de sus casos de uso más fuertes. Combina:

• El proceso en cuatro fases de SKILL.md para investigar y entender la inestabilidad
• condition-based-waiting.md y el ejemplo en TypeScript para reemplazar conjeturas de tiempos por esperas basadas en condiciones
• find-polluter.sh para encontrar tests que contaminan estado o crean archivos inesperados

Juntas, estas herramientas te ayudan a convertir tests poco fiables en comprobaciones estables y deterministas.

¿systematic-debugging es solo para tests o también para bugs en producción?

El proceso aplica a cualquier problema técnico:

• Fallos de tests e inestabilidad
• Bugs e incidentes en producción
• Problemas de rendimiento
• Fallos de build e integración

Los ejemplos y utilidades se orientan más a flujos de testing y desarrollo, pero las fases y principios son explícitamente aplicables también a escenarios de producción.

¿Qué pasa si estoy bajo presión de tiempo y solo necesito un arreglo rápido?

La skill está escrita específicamente para resistir el impulso de "solo un arreglo rápido". Argumenta que:

• Correr sin investigar la causa raíz lleva a dar vueltas y rehacer trabajo
• Las correcciones que solo tratan síntomas suelen crear nuevos problemas

En la práctica, dedicar unos minutos a seguir la Fase 1 y la Fase 2 suele ahorrar tiempo en conjunto, incluso en incidentes urgentes.

¿Tengo que seguir siempre las cuatro fases completas?

La intención de systematic-debugging es que saltar fases sea la excepción, no la norma. Para problemas menores y plenamente entendidos (por ejemplo, un pequeño refactor donde ves el fallo de inmediato), puedes comprimir los pasos. Pero si:

• El problema es recurrente
• No entiendes del todo por qué ocurre
• Correcciones anteriores han fallado

…entonces se recomienda encarecidamente seguir el proceso completo de cuatro fases.

¿Cómo se relacionan el rastreo de causa raíz y defense-in-depth?

root-cause-tracing.md te ayuda a seguir un bug desde el error visible hacia atrás, a través de las cadenas de llamadas, hasta el disparador original. defense-in-depth.md muestra después cómo evitar bugs similares:

• Corrigiendo en la fuente real
• Añadiendo validación en múltiples capas

Por ejemplo, si git init falla en el directorio equivocado, el rastreo muestra qué función pasó la ruta incorrecta, y defense-in-depth añade validación y guardas para que las rutas inválidas se rechacen antes.

¿Puedo usar la skill sin copiar código del repositorio?

Sí. El valor principal de systematic-debugging es el proceso estructurado de depuración descrito en SKILL.md. Puedes:

• Seguir las fases y reglas directamente en tu propio entorno
• Aplicar los patrones de investigación y análisis a cualquier lenguaje o stack

Las ayudas en TypeScript y Bash son aceleradores opcionales, especialmente para entornos JS/TS y tipo Unix.

¿Dónde puedo explorar todo lo que incluye systematic-debugging?

Tras la instalación, abre la vista de archivos o repositorio de obra/superpowers bajo skills/systematic-debugging. Los archivos clave que debes revisar son:

• SKILL.md
• condition-based-waiting.md
• condition-based-waiting-example.ts
• defense-in-depth.md
• root-cause-tracing.md
• find-polluter.sh

Con ellos obtendrás el flujo completo de trabajo de systematic-debugging más herramientas concretas para depuración y estabilización de tests.