La habilidad /diagnosing-bugs

Fuente: The /diagnosing-bugs Skill — traducción comunitaria no oficial al español.

Qué hace

diagnosing-bugs ejecuta un diagnóstico de seis fases sobre un error difícil o una regresión de rendimiento: construye una reproducción, la minimiza, ordena hipótesis, instrumenta, corrige con un test de regresión, limpia.

No deja que el agente forme una teoría hasta que exista un bucle de retroalimentación ajustado: un comando nombrado, ya ejecutado una vez, que sale en rojo con este error y en verde cuando se corrige. El comportamiento por defecto de un agente de código ante un informe de error es leer código y adivinar; esta habilidad lo bloquea. Si no existe un comando capaz de salir en rojo, no hay Fase 2. Esa única compuerta es para lo que existe la habilidad. Todo lo posterior (bisección, prueba de hipótesis, instrumentación) es mecánico una vez que existe la señal.

Cuándo usarla

Escribe /diagnosing-bugs, o el agente la usará por su cuenta cuando una tarea encaje: es invocada por el modelo, y se dispara con «diagnose» / «debug this» o ante un informe de que algo está roto, lanzando errores, fallando, o lento.

Úsala en los difíciles: un error que resiste una primera mirada, un flake intermitente, una regresión que se coló entre dos estados buenos conocidos. Es pesada por diseño, y la herramienta equivocada para una pregunta que quieres responder en un mensaje.

Tu situación	A dónde ir
Un defecto específico que puedes describir como síntoma	Esta habilidad
Un endpoint lento o una regresión de tiempos con un antes y después conocidos	Esta habilidad: tiene una rama de rendimiento (mide una base, luego biseca)
«¿Dónde están los cuellos de botella en esta base de código?», sin síntoma específico	No esta habilidad. Diagnostica una falla conocida, no audita
Un informe de error crudo de otra persona, aún sin confirmar ni redactar	triaje primero
Código desechable para responder una pregunta de diseño, no perseguir un defecto	prototype
Construir un comportamiento planificado con tests primero	tdd
No existe una buena costura para fijar el error	improve-codebase-architecture: esta habilidad deriva hacia allá por sí misma

El bucle ajustado es la habilidad

La Fase 1 recibe un esfuerzo desproporcionado porque es la única fase difícil. La habilidad da una escalera de formas de construir el bucle, más o menos en orden de preferencia:

1. Un test que falla en la costura que alcance el error.
2. Un script curl o HTTP contra un servidor dev en ejecución.
3. Una invocación CLI con una entrada fixture, comparada contra una snapshot buena conocida.
4. Un script de navegador headless que afirma sobre DOM, consola o red.
5. Una captura reproducida: una solicitud, payload o log de eventos guardados, ejecutados por el camino de código de forma aislada.
6. Un harness desechable: un subconjunto mínimo del sistema, una llamada a función.
7. Un bucle de propiedades o fuzz, para «salida a veces incorrecta».
8. Un harness de bisección que puedas entregar a git bisect run.
9. Un bucle diferencial: misma entrada, versión vieja contra nueva.
10. Un script bash con humano en el bucle, último recurso. La habilidad trae scripts/hitl-loop.template.sh para esto: el agente ejecuta el script, tú sigues prompts en tu terminal, y tus respuestas vuelven como salida parseable.

Un bucle no es la meta. Ajustado lo es: rápido (segundos), determinista (mismo veredicto cada vez), afilado (afirma tu síntoma exacto, no «no crasheó»), y ejecutable por el agente sin supervisión. Un bucle flaky de 30 segundos apenas es mejor que ninguno. Para un error que solo aparece a veces, el objetivo no es una reproducción limpia sino una tasa de reproducción más alta: repite el disparador en bucle, paraleliza, añade estrés, inyecta sleeps, hasta que la tasa del flake sea lo bastante alta para depurar contra ella.

Cuando genuinamente no puede construir uno, tiene instrucciones de detenerse y decirlo, listar lo que intentó, y pedirte acceso al entorno, un artefacto capturado, o permiso para añadir instrumentación temporal. No debería pasar a hipotetizar de todos modos.

Las compuertas entre fases

Las fases son compuertas, no una lista. Cada una se niega a abrirse hasta que algo específico sea verdad.

Compuerta	Qué tiene que ser verdad
Hacia la Fase 2	Un comando nombrado, ya ejecutado y pegado con su salida, que puede salir en rojo con este error
Hacia la Fase 3	La reproducción está reproducida y minimizada: cada elemento restante es determinante
Hacia la Fase 4	Existen 3–5 hipótesis ordenadas y falsables, cada una con su predicción, mostradas a ti antes de probar ninguna
Hacia la Fase 5	Las sondas mapean a una predicción específica, una variable a la vez, cada log de depuración etiquetado estilo [DEBUG-a4f2] para que la limpieza sea un grep
Listo	La reproducción original ya no reproduce, la instrumentación desapareció, y la hipótesis que resultó correcta está escrita en el mensaje de commit

La Fase 5 tiene una válvula de escape que vale conocer. El test de regresión se escribe antes de la corrección, pero solo si existe una costura correcta para él: una donde el test ejercite el patrón real del error tal como ocurre en el sitio de llamada. Donde la única costura disponible es demasiado superficial, la habilidad debe decirlo en vez de escribir un test que dé falsa confianza. Esa ausencia es en sí el hallazgo, y es lo que deriva el post-mortem a improve-codebase-architecture.

Preguntas frecuentes

Se dispara con preguntas rápidas donde yo solo quería una respuesta directa. Este es el problema más reportado de la habilidad, y es real. En GPT-5.6-Sol especialmente, los usuarios reportan que se dispara ante una simple descripción de un problema: «el modelo dispara la habilidad diagnosing-bugs, bastante formal, en vez de eso. Luego construye un escenario de reproducción (a menudo armando un escenario mock de valor limitado) antes de darme una respuesta o sugerencia. Esto resulta en demoras considerables.» Cuatro personas distintas reportaron la misma forma en el issue #578. La corrección aceptada es empezar con un enfoque más ligero y subir a este más pesado solo donde el problema lo amerite, pero ese cambio no ha aterrizado. La habilidad está calibrada contra el comportamiento de invocación de Claude Code; un modelo con un umbral de activación más bajo la sobredispara. Hasta que se gradúe, la solución práctica es decir lo que quieres («solo responde esto, no diagnostiques») o desactivar su invocación por modelo en tu harness.

¿Puedo apuntarla a una base de código y preguntar dónde están los problemas de rendimiento? No. Diagnostica una falla que ya puedes nombrar. Su rama de rendimiento es para una regresión con síntoma (establecer una medición base, luego bisecar, medir primero y corregir después), no para un barrido proactivo. Una habilidad para la versión proactiva fue propuesta y cerrada; hoy no hay habilidad para eso.

¿Se detiene y me pregunta antes de escribir la corrección? No. Solo la Fase 3 tiene un punto de control humano: la lista ordenada de hipótesis se te muestra antes de probar ninguna, y avanza con su propio orden si estás fuera. No hay compuerta entre instrumentación y corrección, así que el agente puede empezar a escribir código antes de que hayas acordado su causa raíz. El issue #124 pide esa compuerta y sigue abierto. Si la quieres, dilo al invocar la habilidad.

Ya pasé /triage sobre este informe de error. ¿Es el mismo trabajo de nuevo? En parte, y ninguna habilidad lo admite. Como lo dijo un lector: «El paso 3 de Triage es esencialmente una instancia superficial y acotada de las Fases 1–2 de diagnosing-bugs, pero ningún archivo menciona al otro.» Triaje hace una pasada acotada de «¿esto es realmente un error, y cuál es la superficie?»; esta habilidad hace la versión a fondo. Pasar triaje primero no se pierde (su verificación suele darte la mayor parte del material crudo de la Fase 1), pero espera rehacerlo bien aquí, y no esperes una referencia cruzada que te lo diga.

¿La salida de reproducción que pega puede filtrar secretos? Podría. La habilidad pide al agente pegar la invocación y su salida, y solicitar artefactos como archivos HAR, volcados de logs y core dumps. Nada de eso se sanitiza por instrucción. El issue #674 plantea exactamente esto (credenciales, tokens, cookies y datos personales viajando a un chat, un issue o un PR) y propone una guarda de redacción. Está abierto y sin implementar. Trata la redacción como tu trabajo por ahora, en particular antes de que la salida vaya a algo público.

Mi escáner de seguridad marcó esta habilidad como de alto riesgo. Snyk la marca, y la marca es un falso positivo. Es la única habilidad del conjunto que trae un script shell ejecutable (hitl-loop.template.sh) junto a instrucciones para ejecutarlo y hacer curl a un servidor dev. .sh publicado más instrucciones de ejecución más HTTP saliente basta para disparar un escáner estático. El script en sí son unas 30 líneas de prompts read -r -p que pausan por entrada humana. El escáner califica la superficie de capacidad, no un exploit probado.

¿Qué pasó con /diagnose? Renombrado a /diagnosing-bugs en v1.0.0. El nombre viejo ya no existe. Todo lo tuyo que encadene /diagnose (una habilidad envoltorio, un prompt guardado) necesita actualizarse.

Funciona si

• Te muestra un comando y su salida en rojo antes de ofrecer una sola teoría. Si la teoría llega primero, la habilidad no está corriendo.
• La falla que reproduce es la que reportaste, no una cercana que encontró en el camino.
• Encoge la reproducción antes de empezar a adivinar, y puede decirte por qué cada pieza restante es determinante.
• Te muestra una lista ordenada de 3–5 hipótesis, cada una con una predicción que podrías falsar, antes de probar ninguna.
• Cada log de depuración que añade lleva una etiqueta como [DEBUG-a4f2], y un grep de esa etiqueta vuelve vacío cuando declara listo.
• El mensaje de commit o PR nombra qué hipótesis tenía razón.
• Cuando no puede fijar el error con un test, lo dice claramente en vez de escribir uno superficial.

Dónde encaja

diagnosing-bugs es una habilidad independiente para usar en cualquier momento. Entras cuando algo está roto y sales cuando la corrección y su test de regresión están dentro; no guarda estado ni necesita configuración previa. ask-matt enruta «algo está roto» aquí.

Dos vecinos importan. improve-codebase-architecture toma el handoff cuando el hallazgo real es que el código no tiene costura para fijar el error; la recomendación se hace después de que la corrección está dentro, cuando hay más información. triage está aguas arriba para errores que llegan como informes crudos de otras personas, y hace una versión más superficial de las mismas dos primeras fases.