debugger

Visión general de debugger skill

Para qué sirve debugger skill

La debugger skill ofrece un flujo de depuración estructurado para encontrar la causa raíz más rápido que con un prompt genérico tipo “¿qué está mal?”. Está pensada para casos en los que el código lanza errores, se comporta de forma inesperada, introduce regresiones tras cambios o falla solo en determinados entornos. En lugar de saltar directamente a una solución, debugger skill impone una secuencia que sí importa en el trabajo real de depuración: reproducir, aislar, analizar, corregir y verificar.

Quién debería instalar debugger skill

Esta debugger skill encaja bien para desarrolladores, agentes de codificación con IA y equipos técnicos que quieren un proceso repetible para Debugging en vez de un troubleshooting improvisado. Resulta especialmente útil si trabajas a menudo a partir de stack traces, logs, reportes de bugs incompletos o pasos de reproducción poco claros. Su valor no está tanto en un conocimiento profundo de un framework concreto como en mejorar la disciplina de depuración entre proyectos.

Qué trabajo te ayuda a resolver

La necesidad real no es “explicar un mensaje de error”. Es convertir un fallo difuso en una ruta de investigación clara: qué cambió, cómo reproducirlo, dónde acotar el alcance, qué evidencia reunir y cómo verificar la corrección final. Por eso esta instalación de debugger resulta más valiosa cuando un equipo está perdiendo tiempo en suposiciones o arreglando síntomas una y otra vez en lugar de la causa.

Por qué destaca debugger skill

Su diferencia útil está en cómo está planteada a nivel operativo. El repositorio incluye:

• un flujo de depuración por fases en SKILL.md
• ayudas rápidas de depuración en references/checklist.md, references/errors.md y references/patterns.md
• un generador práctico de informes en scripts/debug_report.py

Esa combinación hace que debugger skill sea mejor para trabajo en vivo tipo incidente que una simple plantilla de prompt. Te da un proceso, una checklist, categorías comunes de fallos y un artefacto útil para el handoff.

Lo que no intenta hacer

No es un depurador específico de un lenguaje, una extensión de IDE ni una plataforma de tracing. No sustituye herramientas de runtime, profilers ni documentación de frameworks. Si tu necesidad principal es hacer stepping interactivo, inspección de memoria o tracing a nivel de protocolo, usa esas herramientas directamente y trata esta guía de debugger como la capa de razonamiento que las rodea.

Cómo usar debugger skill

Contexto de instalación y ruta del repositorio

La skill está en skills/debugger dentro de zhaono1/agent-playbook. Si usas un cargador de skills compatible con orígenes de GitHub, instala desde el repositorio y apunta a la skill debugger. Un patrón habitual es:

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

Si tu configuración es distinta, lo importante es cargar el directorio skills/debugger para que el agente pueda acceder a SKILL.md y también a los archivos de apoyo de references/ y scripts/.

Lee primero estos archivos

Para adoptarla rápido, lee en este orden:

1. skills/debugger/SKILL.md
2. skills/debugger/references/checklist.md
3. skills/debugger/references/patterns.md
4. skills/debugger/references/errors.md
5. skills/debugger/scripts/debug_report.py

Este recorrido refleja el uso real de debugger: primero el flujo, luego las heurísticas de investigación, después las categorías de error y, por último, el apoyo para documentar.

Cómo se activa debugger skill en la práctica

El repositorio está pensado para activarse cuando un usuario reporta:

• un error o una excepción
• un comportamiento inesperado
• “debug this”
• “why isn’t this working?”

En la práctica, debugger skill funciona mejor cuando formulas explícitamente la petición como una tarea de depuración y aportas evidencia. Ejemplo:

“Use the debugger skill. This API returns 500 only in staging. Expected 200. Started after yesterday’s deploy. Here is the stack trace, the endpoint, and the last 3 commits.”

Ese prompt es mucho más sólido que “fix this bug.”

Qué entradas necesita debugger skill

Un buen uso de debugger depende de entradas concretas. Aporta tantas como puedas:

• texto exacto del error
• stack trace
• comportamiento esperado frente al real
• pasos reproducibles
• cambios recientes de código o configuración
• detalles del entorno
• logs relevantes
• alcance acotado a archivo o componente

El flujo de la skill asume recopilación de evidencia, así que la falta de pasos de reproducción o de salida real afecta más a la calidad del resultado que la falta de detalle de implementación.

Cómo convertir una petición vaga en un buen prompt para debugger

Prompt débil:
“Why does this fail?”

Prompt más sólido:
“Use the debugger skill to diagnose this failure. After upgrading dependencies, npm test fails in auth.spec.ts with TypeError: Cannot read properties of undefined. Expected tests to pass. Actual behavior: 6 failures on CI, 0 locally. Recent changes: lockfile update and config edit. Please help reproduce, isolate likely causes, rank hypotheses, and suggest the smallest safe fix.”

Por qué funciona:

• define el objetivo de depuración
• da el comportamiento esperado frente al real
• incluye la diferencia entre entornos
• incluye cambios recientes
• pide investigar antes de parchear

Flujo de trabajo recomendado con debugger skill

Una guía práctica de debugger para uso real:

1. Reproduce el problema exactamente.
2. Registra el comportamiento esperado frente al real.
3. Revisa cambios recientes con git log --oneline -10.
4. Reúne logs o trazas.
5. Aísla con una repro mínima o búsqueda binaria.
6. Relaciona el fallo con una categoría de error.
7. Formula hipótesis de causa raíz.
8. Prueba la corrección más pequeña con más probabilidad de funcionar.
9. Verifica con cobertura de regresión.

Esto es, en esencia, lo que codifica la skill, pero seguirlo de forma explícita ayuda cuando el agente empieza a proponer fixes demasiado pronto.

Usa los archivos de referencia como apoyo para decidir

Los archivos de apoyo son breves, pero cambian mucho la calidad de la salida:

• references/checklist.md mantiene la sesión bien encarrilada: reproducir, aislar, causa raíz, fix, cobertura de regresión.
• references/patterns.md resulta útil cuando el problema es amplio o ruidoso; sugiere búsqueda binaria, logging dirigido y reducción a una repro mínima.
• references/errors.md ayuda a clasificar fallos comunes como acceso a null, race conditions, desajustes de configuración y cambios en la forma de los datos.

Úsalos cuando la primera respuesta de debugger te parezca genérica. Son mejores para afinar la ruta de investigación que para aprender sintaxis.

Genera un informe de depuración reutilizable

Si quieres un artefacto documentado de la investigación, usa:

python skills/debugger/scripts/debug_report.py --name "Checkout timeout in staging" --owner payments

Esto crea una plantilla de informe en markdown con secciones para resumen, entorno, pasos de reproducción, logs, causa raíz, fix, pruebas de regresión y acciones de seguimiento. Para depuración en equipo, es una de las partes más prácticas del repositorio porque convierte una investigación efímera en algo revisable.

Mejores casos de uso de debugger para Debugging

Esta debugger skill resulta más útil cuando:

• el bug es reproducible pero no evidente
• hay logs, pero generan mucho ruido
• el fallo apareció después de un cambio
• el problema cruza código, configuración y entorno
• necesitas un flujo de triage disciplinado antes de tocar el código

Tiene menos valor para errores de sintaxis mínimos que puedes detectar al instante o para incidentes muy específicos del dominio que exigen contexto operativo propietario al que el agente no puede acceder.

Consejos prácticos para mejorar el uso de debugger skill

Pide a la skill que separe:

• hechos
• hipótesis
• siguientes comprobaciones
• fix propuesto
• pasos de verificación

Esa estructura evita una confianza prematura. También conviene pedirle que ordene las causas probables por prioridad y que diga qué evidencia refutaría cada una. Así debugger skill deja de ser un “adivinador inteligente” y se convierte en un mejor compañero de investigación.

Preguntas frecuentes sobre debugger skill

¿Es esta debugger skill mejor que un prompt normal?

Por lo general sí, cuando el problema tiene varios pasos. Un prompt genérico suele saltar del síntoma a una solución supuesta. debugger skill funciona mejor cuando necesitas acotar de forma sistemática, reunir evidencia y verificar. Si el bug es trivial y se ve completo en un solo fragmento, un prompt normal puede bastar.

¿La instalación de debugger es apta para principiantes?

Sí, porque el flujo principal es simple y concreto. Los principiantes se benefician del proceso por fases y de la checklist. El principal matiz es que la skill asume que puedes aportar cierta evidencia, como logs, stack traces o pasos de reproducción. Sin eso, cualquier guía de debugger tenderá más a la especulación.

¿Puedo usar esta debugger skill con cualquier lenguaje o stack?

En gran medida sí. debugger skill está orientada al proceso, no a un lenguaje concreto. Sus ejemplos de error son generales y no dependen de un framework específico. Eso la hace portable, aunque también significa que quizá debas añadir tú mismo detalles propios de tu stack para obtener mejores resultados.

¿Cuándo no debería usar debugger skill?

Evítala cuando:

• necesitas depuración interactiva en runtime más que ayuda de razonamiento
• el problema es puramente operativo y el agente no puede acceder al sistema
• el bug es un typo de una sola línea ya identificado
• necesitas conocimiento específico de un proveedor que el repositorio no contiene

En esos casos, conviene usar primero herramientas directas o documentación del dominio.

¿Ayuda con el handoff entre equipos y el seguimiento de incidentes?

Sí. El script debug_report.py es la señal más clara de que esta debugger skill está pensada para algo más que chats puntuales. Ayuda a convertir una sesión de depuración en un informe reutilizable con ownership, pasos de reproducción, causa raíz, fix y tareas de seguimiento.

Cómo mejorar debugger skill

Da a debugger skill evidencia, no solo síntomas

La forma más rápida de mejorar la salida de debugger es incluir evidencia en bruto:

• comando exacto ejecutado
• texto completo del error
• entrada que provoca el fallo
• entorno en el que se rompe
• rango de commits recientes
• lo que ya probaste

“Here is the stack trace and the last good commit” es muchísimo mejor que “it’s broken after my changes.”

Fuerza una repro mínima cuanto antes

Un fallo común al usar debugger es investigar demasiada superficie a la vez. Pide a la skill que te ayude a crear el caso reproducible más pequeño posible. Eso suele eliminar ruido de la configuración del framework, servicios no relacionados o estado obsoleto, y hace que la causa raíz aparezca antes.

Pide que ordene las hipótesis

Cuando hay varias causas plausibles, indica a debugger skill que las ordene por probabilidad y por facilidad de verificación. Así obtienes un mejor orden de investigación. Ejemplo:

“List the top 3 root-cause hypotheses, what evidence supports each, and the next cheapest check to confirm or reject them.”

Esto resulta especialmente útil en tests flaky, fallos de integración y config drift.

Separa la causa raíz de la calidad del fix

Otro problema habitual es aceptar el primer fix que hace desaparecer el síntoma. Usa la guía de debugger para preguntar:

• por qué ocurrió
• qué condición lo permitió
• qué prueba de regresión debería demostrar que sigue corregido

Esto importa especialmente en problemas recurrentes como manejo de null, race conditions y configuraciones desalineadas.

Mejora la primera respuesta con contexto del repositorio

Si el bug está en tu propio código, aporta:

• archivos sospechosos
• límite de paquete o servicio
• momento del despliegue
• archivos de configuración implicados
• si el problema ocurre solo en local, CI, staging o producción

debugger skill funciona mucho mejor cuando puede relacionar la evidencia con los límites del sistema en vez de razonar solo a partir de un stack trace pegado.

Usa las referencias para afinar respuestas flojas

Si la primera respuesta te parece genérica, indícale explícitamente al agente que use:

• references/checklist.md para completar el proceso
• references/patterns.md para métodos de aislamiento
• references/errors.md para relacionar el fallo con una familia de errores

Es una forma práctica de mejorar los resultados de debugger sin reescribir todo el prompt.

Itera después de la primera pasada de depuración

Un buen uso de debugger es iterativo. Después de la primera respuesta:

1. ejecuta una comprobación sugerida
2. vuelve con el resultado
3. pide a la skill que actualice las hipótesis
4. solo entonces edita el código

Es en este bucle donde debugger skill resulta más útil que una guía estática de debugger. Te ayuda a converger en lugar de generar una sola respuesta larga y especulativa.

Añade prueba de regresión antes de cerrar

La checklist del repositorio incluye explícitamente cobertura de regresión, y ese es el punto correcto para cerrar. Pide a debugger skill que proponga la prueba, aserción o comprobación de monitorización más pequeña que detectaría el problema la próxima vez. Un fix sin verificación suele equivaler a un Debugging incompleto, especialmente en fallos intermitentes o dependientes del entorno.