Inicio / Skills / Productividad del desarrollador / Systematic Debugging
Productividad del desarrollador

Systematic Debugging

Jesse VincentMITIdioma del Skill: Inglés
Licencia verificadaIncluye scriptsRiesgo medio
DemostraciónEjecución real · claude-sonnet-5-5 · octubre de 2026
Using the systematic-debugging skill: our checkout API started returning intermittent 500 errors after yesterday's deploy. The log says "TypeError: Cannot read properties of undefined (reading id)" at orderService.js line 88. A teammate says to just wrap that line in a try/catch so users stop seeing errors. What should we do?
Skill: systematic-debugging

Don't add the try/catch yet. It hides the symptom without fixing anything. Checkout is a write path, so swallowing the error there is risky. If order is undefined at line 88, the code either carries on with a half-built order or returns a success to the user for an order that wasn't created. That can mean silent data loss or a charge with no order, which is worse than a visible 500.

Phase 1: find the root cause

  1. Read the full stack trace. Check what undefined is at line 88. It's the object whose .id is being read, for example order.id, user.id or cart.id. Then check who called this function and what they passed.
  2. Check what changed in yesterday's deploy. Diff the release and look for anything touching orderService.js, its callers, the shape of the data it reads (DB queries, migrations, upstream API responses), dependency bumps, and config or env changes. The timing points to the deploy, so that diff is the highest-value evidence.
  3. Work out why it's intermittent. Intermittent usually means the failure depends on the input or the timing. Compare failing and succeeding requests for these differences:
    • Particular users, carts or payment methods, such as guest vs. logged-in, empty cart, or a coupon.
    • A race condition, such as a read before a write commits, or a missing await.
    • A cache miss, or one instance or region running a different version or config.
    • A lookup that returns null or undefined for some records, such as a .find() with no match or a missing relation.
  4. Add logging if the logs don't answer this. Log the inputs entering and leaving the function that contains line 88. Log the request ID, user, cart contents, and the result of whatever lookup feeds line 88. Then collect several failing and passing cases.
  5. Trace the bad value backward to where the undefined first appears. Fix it there, not at line 88.

If users are hurting right now

  • Roll back yesterday's deploy if the diff points to it or you can't find the cause quickly. It stops the errors without hiding anything, and you can debug in peace.
  • If you can't roll back, a guard is acceptable as a temporary mitigation. It should fail explicitly, with an early check that logs the context and returns a clear error or 4xx, rather than a blanket try/catch. It must not let checkout continue with bad state. Treat it as a stopgap and keep investigating.

Once you find the cause

Write a failing test that reproduces it, fix it at the source, and verify the test passes. Then consider validating at the boundary where the bad data enters, so this class of bug fails loudly and early.

The directory I'm in has no git repo, and I haven't seen orderService.js. If you point me at the repo, the deploy diff, or a few failing-request logs, I can start on steps 1–3.

Real run in an isolated folder with only this skill installed. Only the Skill and Read tools were enabled, so no command was run and no file was written. The example is fictional. The scenario is invented and the model had no access to the code, so it laid out the investigation steps. The bundled shell script was not run.

Qué hace

Establece una regla inquebrantable: no aplicar correcciones sin investigar antes la causa raíz. La fase 1 lee los errores por completo, reproduce el problema, revisa los cambios recientes y reúne evidencias en cada límite de componente. La fase 2 busca ejemplos que funcionen y enumera todas las diferencias. La fase 3 formula una hipótesis y la prueba con el cambio más pequeño posible. La fase 4 escribe una prueba que falle, aplica una única corrección y la verifica. Tras tres correcciones fallidas, se detiene y te pide cuestionar la arquitectura en lugar de intentar un cuarto parche. También enumera las excusas que llevan a adivinar («emergencia», «solo una corrección rápida») y tus propias señales de que se está omitiendo el proceso. Los archivos de apoyo cubren el rastreo regresivo de la causa raíz, la defensa en profundidad y la sustitución de tiempos de espera arbitrarios por sondeo basado en condiciones (con un ejemplo en TypeScript).

Ideal para

Fallos de pruebas, errores en producción, pruebas intermitentes, problemas de compilación e integración, especialmente bajo presión de tiempo.

Notas y riesgos

Riesgo medio: los pasos de investigación indican al modelo que añada registros y ejecute comandos de diagnóstico, y los ejemplos incluyen `env | grep` y `security find-identity`, por lo que las variables de entorno o los detalles del almacén de credenciales pueden acabar en la conversación; enmascara los secretos antes de compartir la salida. El script incluido `find-polluter.sh` ejecuta `npm test <file>` una vez por cada archivo de prueba coincidente para encontrar la prueba que deja archivos atrás, lo que ejecuta las pruebas de tu proyecto y cualquier efecto secundario que tengan. No se elimina nada y nada usa la red. En este listado se omitieron los propios escenarios de prueba del autor y el registro de creación. Se probó con un error descrito sin acceso al código; no se ejecutaron los scripts.

SKILL.md original7 archivos en este paquete