systematic-debugging

Visión general de la skill systematic-debugging

La skill systematic-debugging ofrece un flujo de depuración estructurado para agentes y desarrolladores que quieren menos arreglos por tanteo y una resolución más rápida de la causa raíz. Su regla central es simple: investiga antes de cambiar código. Por eso encaja muy bien en fallos de tests, comportamientos intermitentes, bugs en producción, problemas de build e incidencias de integración donde un “arreglo rápido” probablemente oculte el problema real.

Para quién encaja mejor esta skill

Usa systematic-debugging si:

• ves una y otra vez arreglos fallidos o solo parciales
• estás depurando con presión de tiempo
• necesitas que un asistente de IA frene y analice antes de parchear síntomas
• quieres un proceso repetible para bugs, tests flaky y comportamientos inesperados

Resulta especialmente útil cuando el problema parece obvio, pero todavía no sabes por qué ocurre.

Qué trabajo resuelve realmente esta skill

El trabajo real no es “producir un fix”. Es:

1. reproducir el problema,
2. rastrear la causa,
3. poner a prueba una explicación cada vez,
4. y solo entonces implementar un fix dirigido.

Puede sonar más lento, pero normalmente reduce retrabajo, parches fallidos y bugs nuevos introducidos por adivinar.

Qué hace diferente a systematic-debugging

La mayoría de prompts corrientes saltan del síntoma a la solución. La systematic-debugging skill toma una postura clara contra eso. El repo insiste en un flujo de trabajo de estilo “Iron Law”: no hay fixes sin investigación previa de la causa raíz.

Además, los archivos que la rodean hacen que la skill sea más práctica que una checklist genérica de depuración:

• root-cause-tracing.md ayuda cuando el error visible está muy lejos de su origen real
• condition-based-waiting.md ayuda con tests async flaky causados por esperas arbitrarias
• defense-in-depth.md ayuda a convertir un fix puntual de validación en una prevención estructural
• find-polluter.sh ayuda a aislar tests que filtran archivos o estado

Tipos de problemas donde systematic-debugging encaja mejor

systematic-debugging for Debugging es una opción muy sólida para:

• tests que fallan y aún no sabes explicar
• tests flaky en CI
• bugs donde fixes anteriores no resolvieron el problema
• errores que aparecen muy abajo en el stack
• mal estado, archivos filtrados, rutas incorrectas, race conditions y problemas de timing

Cuándo esta skill encaja peor

Omítela solo cuando la tarea en realidad no sea depuración, por ejemplo:

• trabajo de funcionalidad sencillo
• refactors rutinarios sin ningún fallo que explicar
• cambios puramente cosméticos

Aun así, si estás reaccionando a un “comportamiento inesperado”, systematic-debugging suele ser el punto de partida más seguro.

Cómo usar la skill systematic-debugging

Contexto de instalación de systematic-debugging

Si usas el patrón Skills CLI que aparece en este ecosistema, instálala con:

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

Después, invócala desde tu entorno de agente o usa su proceso manualmente leyendo los archivos fuente dentro de la carpeta de la skill.

Qué archivos leer primero de systematic-debugging

Si quieres una guía de systematic-debugging rápida y con alta señal, léelos en este orden:

1. skills/systematic-debugging/SKILL.md
2. skills/systematic-debugging/root-cause-tracing.md
3. skills/systematic-debugging/condition-based-waiting.md
4. skills/systematic-debugging/defense-in-depth.md
5. skills/systematic-debugging/find-polluter.sh

Por qué este orden:

• SKILL.md presenta el flujo obligatorio de cuatro fases
• root-cause-tracing.md ayuda cuando los síntomas aparecen muy aguas abajo
• condition-based-waiting.md da un patrón de corrección concreto para tests async flaky
• defense-in-depth.md ayuda a reforzar el fix final
• find-polluter.sh es un aislador práctico para contaminación entre tests

Qué información necesita la skill de tu parte

La calidad del uso de systematic-debugging depende mucho de lo que le des como entrada. Dale a la skill:

• mensaje de error exacto
• stack trace
• pasos de reproducción
• comportamiento esperado vs. comportamiento real
• detalles del entorno, como OS, runtime, test runner y si ocurre solo en CI o solo en local
• cambios recientes en el código
• si el problema es determinista o flaky
• qué has probado ya

Sin esto, el modelo tendrá más tendencia a especular.

Cómo convertir un bug report básico en un buen prompt

Prompt débil:

Test is failing. Help fix it.

Prompt más sólido:

Use systematic-debugging on this failing test. Do not propose a fix until root cause investigation is complete. Here is the exact error, stack trace, reproduction command, recent changes, and the one behavior difference between local and CI. Identify likely root causes, suggest the minimum investigation steps, and keep hypotheses separate.

Ese prompt funciona mejor porque pide resultados de investigación antes de pasar a la implementación.

Una plantilla de prompt práctica

Usa esta estructura para el uso de systematic-debugging:

• Issue: qué falló
• Reproduction: comando exacto o pasos
• Evidence: logs, trace, capturas, aserción fallida
• Scope: local, CI, una máquina, todos los entornos
• Recent changes: commits, actualizaciones de dependencias, cambios de config
• Constraints: no se puede cambiar la API, hace falta un parche mínimo, hay deadline, etc.
• Request: investigar primero la causa raíz y luego proponer un único fix

Ejemplo:

Use systematic-debugging for this Jest failure. Repro: npm test src/foo.test.ts. Error: Timeout waiting for TOOL_RESULT event after 5000ms. It fails in CI and under parallel runs, not always locally. We recently changed thread event handling. First investigate root cause, then propose one focused fix and one validation plan.

Sigue el flujo de cuatro fases en orden

El repo se apoya en cuatro fases. En la práctica, conviene usarlas así:

1. Investigación de causa raíz
   Lee el error con cuidado, reprodúcelo de forma fiable, revisa qué cambió y recopila evidencia.
2. Análisis de patrones
   Busca patrones de timing, entorno, forma de entrada, fuga de estado o cadena de llamadas.
3. Prueba de hipótesis
   Formula una explicación cada vez y compruébala. Evita cambiar varias variables a la vez.
4. Implementación
   Solo cuando la evidencia apunte a una causa, haz el fix y verifícalo.

Si la Fase 1 es floja, todo lo que viene después empeora.

Cómo usar systematic-debugging con tests flaky

Este repo ofrece una ayuda especialmente práctica aquí. Si un test depende de sleep, setTimeout o esperas arbitrarias, revisa condition-based-waiting.md y condition-based-waiting-example.ts.

El cambio clave es este:

• patrón malo: adivinar cuánto tardará un proceso async
• patrón mejor: esperar a la condición que demuestra que ya terminó

Importa porque muchos fallos “aleatorios” en realidad son race conditions ocultas por suposiciones de timing.

Cómo usarlo cuando el síntoma aparece aguas abajo

Si el error aparece muy abajo en un stack o lejos de donde se originaron los datos erróneos, usa root-cause-tracing.md. El flujo es:

• identificar la línea que falla de forma inmediata
• rastrear una llamada hacia arriba
• seguir rastreando hasta encontrar dónde apareció por primera vez el estado incorrecto
• corregir el origen, no solo el punto donde explota

Esta es una de las partes más valiosas de la systematic-debugging skill, porque muchos bugs son síntomas de un estado inválido introducido antes.

Cómo usar el detector de contaminación entre tests

Para tests que dejan archivos, directorios o estado residual, merece la pena leer find-polluter.sh antes de improvisar tu propio bucle.

Patrón de uso:
./find-polluter.sh <file_or_dir_to_check> <test_pattern>

Ejemplo del script:
./find-polluter.sh '.git' 'src/**/*.test.ts'

Esto resulta útil cuando el fallo lo causa una contaminación oculta entre tests y no el test que aparentemente falla.

Flujo de trabajo habitual que da mejores resultados

Un flujo fiable para la instalación de systematic-debugging y su primer uso sería:

1. instalar la skill
2. leer SKILL.md
3. recopilar evidencia exacta del fallo
4. pedir al agente que investigue sin arreglar
5. elegir la hipótesis con mejor respaldo en la evidencia
6. probar solo esa hipótesis
7. implementar un único fix enfocado
8. añadir validación o defense-in-depth si el bug venía de datos inválidos o de múltiples rutas de entrada

Esto evita el fallo más común: tocar código antes de entender qué está pasando.

Qué no hacer con esta skill

No le pidas a systematic-debugging que:

• genere muchas soluciones de inmediato
• reescriba zonas grandes antes de reproducir el bug
• “simplemente haga pasar el test” sin explicación
• parchee varias causas sospechosas a la vez

Esos atajos chocan de frente con el diseño de la skill y reducen la calidad del resultado.

FAQ de la skill systematic-debugging

¿systematic-debugging es solo para bugs complejos?

No. La postura del repo es que incluso los bugs simples tienen una causa raíz. La skill aporta más valor justo cuando un problema parece lo bastante simple como para tentar a aplicar un parche rápido.

¿En qué se diferencia de un prompt normal de depuración?

Un prompt normal suele premiar la velocidad y los fixes especulativos. systematic-debugging obliga al modelo a separar investigación, hipótesis e implementación. Eso normalmente produce menos parches incorrectos y mejores explicaciones.

¿systematic-debugging es apta para principiantes?

Sí, siempre que puedas aportar evidencia concreta. El proceso es estricto, pero los pasos son fáciles de entender: reproducir, inspeccionar, rastrear, probar una idea y luego arreglar. De hecho, a principiantes puede beneficiarles más porque evita el ensayo y error aleatorio.

¿Cuándo no debería usar systematic-debugging?

No la uses como patrón principal para:

• ideación de funcionalidades
• brainstorming de arquitectura
• generación de código no relacionada con un fallo
• ajustes puramente visuales sin comportamiento roto que explicar

Úsala cuando algo va mal y necesitas encontrar la causa, no solo poner un parche.

¿systematic-debugging ayuda con fallos que solo aparecen en CI?

Sí. Encaja muy bien con fallos que solo ocurren en CI o que son sensibles a la carga porque te empuja a comparar entornos, reproducir condiciones e inspeccionar supuestos de timing y estado en lugar de adivinar.

¿Puede ayudar con tests async flaky?

Sí, y este repo está por encima de la media en ese punto. condition-based-waiting.md y el archivo de ejemplo TypeScript ofrecen una vía concreta para abandonar las esperas arbitrarias y pasar a una sincronización basada en condiciones.

¿La skill incluye tooling o solo consejos?

Principalmente ofrece guía de proceso, junto con algunos archivos complementarios concretos. La ayuda más práctica es find-polluter.sh, y el ejemplo de espera basada en condiciones se puede reutilizar directamente en algunos entornos de test con TypeScript.

¿Puedo usar systematic-debugging con cualquier stack?

En general, sí. El método central no depende del stack. Los ejemplos se inclinan hacia TypeScript, shell y flujos de testing, pero el proceso de investigación funciona en distintos lenguajes y frameworks.

Cómo mejorar la skill systematic-debugging

Aporta mejor evidencia antes de pedir un fix

La mayor palanca está en la calidad de la entrada. Para obtener mejores resultados con systematic-debugging, incluye:

• un comando exacto de reproducción
• un bloque exacto de error
• un test o archivo mínimo que falle
• qué cambió recientemente
• si el problema se reproduce siempre o no

Eso ayuda a que la skill trabaje sobre evidencia y no sobre inferencias.

Pide resultados de investigación antes de la implementación

Un prompt de alto rendimiento bloquea explícitamente el fix prematuro. Por ejemplo:

Use systematic-debugging. First produce root-cause investigation findings and the top 2 hypotheses with evidence for each. Do not suggest code changes yet.

Esto mejora la calidad de la respuesta porque introduce un punto de control entre leer el síntoma y editar código.

Obliga a trabajar con una hipótesis cada vez

Un fallo habitual es mezclar varias causas posibles dentro del mismo parche. Pide:

• la hipótesis principal
• la prueba más pequeña que podría refutarla
• qué resultado la confirmaría

Así mantienes el flujo alineado con la intención de la skill.

Mejora los prompts para escenarios de tests flaky

Cuando uses systematic-debugging for Debugging en tests flaky, aporta:

• frecuencia de éxito/fallo
• si los fallos se correlacionan con paralelismo o con CI
• cualquier uso de sleeps, waits, retries o polling
• el evento o estado exacto que el test intenta observar

Eso facilita mucho que el modelo detecte cuándo condition-based-waiting.md es el patrón complementario adecuado.

Usa los archivos cercanos al código fuente, no solo SKILL.md

Si la primera respuesta suena genérica, dirige el modelo a la documentación de apoyo:

• root-cause-tracing.md para síntomas aguas abajo
• condition-based-waiting.md para problemas de timing o race conditions
• defense-in-depth.md para estrategia de validación
• find-polluter.sh para contaminación entre tests

La skill mejora cuando el agente usa ese material complementario especializado y no solo el flujo principal.

Acota el alcance tras la primera pasada

Si el primer resultado es demasiado amplio, afínalo con:

• el subsistema exacto que hay que inspeccionar
• el límite sospechoso por el que entran datos erróneos
• el primer commit donde apareció el problema
• la reproducción mínima que falla

Los prompts de depuración amplios suelen producir planes de depuración amplios. Un alcance más estrecho da mejor trabajo de causa raíz.

Mejora el fix final, no solo el diagnóstico

Una vez encontrada la causa raíz, pide:

• el fix mínimo
• una prueba de regresión
• una capa de validación que evite que vuelva a ocurrir

Aquí es donde defense-in-depth.md resulta útil. Si el bug venía de entradas inválidas o de supuestos que podían esquivarse, un único parche puede no bastar.

Vigila estos modos de fallo habituales

El mal uso de systematic-debugging suele venir de:

• texto de error incompleto
• ausencia de una reproducción fiable
• pedir fixes demasiado pronto
• cambiar varias cosas entre ejecuciones de prueba
• dar por demostrada la primera explicación plausible

Si evitas eso, la skill aporta mucho más valor que un prompt genérico de “depura esto”.