La habilidad /triage

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

Qué hace

triage recorre los issues en el gestor de tu proyecto, moviendo cada uno por una pequeña máquina de estados de roles de triaje (un rol de categoría y un rol de estado) y dejando atrás un informe listo para agentes, una pregunta específica para quien reportó, o un issue cerrado con una razón registrada.

Es solo para issues que tú no creaste. Reportes de errores en bruto, solicitudes de funcionalidad entrantes, un pull request externo que llegó sin avisar: trabajo que aterrizó en el gestor desde fuera, en la forma en que lo dejó quien reportó. Los tickets que produjo to-tickets ya están listos para agentes por construcción, y ejecutar triage sobre ellos es trabajo desperdiciado en el mejor caso. La regla es plana: /triage es solo para issues entrantes, no para issues que creaste tú.

Lo segundo que la separa de etiquetar a mano: recomienda y espera. Te dice su decisión de categoría y estado con razonamiento, más lo que encontró en la base de código, y no aplica nada hasta que tú lo diriges.

Cuándo usarla

La invocas escribiendo /triage y luego describiendo lo que quieres en lenguaje llano. El agente no la usará por su cuenta. “Muéstrame lo que necesite mi atención”, “veamos el #42”, “mueve el #42 a ready-for-agent”.

Lo que tienes	A dónde ir
Un gestor lleno de reportes en bruto de otra gente	`/triage`
Una idea propia aproximada, sin nada escrito	grill-with-docs
Una conversación acordada para convertir en spec	to-spec
Una spec para dividir en tickets listos para agentes	to-tickets
Un error confirmado que necesita causa raíz, no etiqueta	diagnosing-bugs

Requisitos previos

triage lee y escribe tu gestor de pendientes, así que setup-matt-pocock-skills tiene que haber configurado ese gestor y su vocabulario de etiquetas primero. Los nombres de roles de abajo son canónicos; las cadenas de etiquetas en tu gestor pueden diferir, y el mapeo es lo que proporciona la configuración. Si tu gestor ya usa los nombres canónicos exactamente, no hay nada que mapear ni nada que configurar.

La configuración del gestor también decide si los pull requests externos cuentan como superficie de solicitud, y quién cuenta como externo. Esa opción está apagada por defecto y ya no es una pregunta de configuración, así que cámbiala en docs/agents/issue-tracker.md si quieres PR en alcance.

La máquina de estados

Cada elemento triado termina llevando exactamente un rol de categoría y un rol de estado. Dos categorías: bug (algo está roto) y enhancement (nueva funcionalidad o mejora). Cinco estados:

Estado	Significa
`needs-triage`	Necesitas evaluarlo. Donde normalmente cae primero un issue sin etiquetar.
`needs-info`	Esperando a quien reportó. Vuelve a `needs-triage` cuando responde.
`ready-for-agent`	Totalmente especificado, con un informe de agente adjunto. Un agente AFK puede tomarlo.
`ready-for-human`	El mismo informe, más por qué esto no se puede delegar: juicio, acceso externo, pruebas manuales.
`wontfix`	Cerrado, con la razón registrada.

Ese es todo el vocabulario, y el invariante de “exactamente un rol de estado” es lo que mantiene las consultas simples. También es el área más pedida de la habilidad: la gente ha pedido un sexto estado para trabajo especificado pero bloqueado por otro issue, para trabajo deferred condicionado a un disparador futuro, y para un estado terminal implemented. Nada de eso se ha publicado. Consulta las preguntas más abajo.

wontfix se divide en tres, y la diferencia importa porque solo una de ellas escribe en la base de conocimiento:

Por qué lo cierras	Qué ocurre
Ya implementado	Un comentario que apunta a dónde ya vive. Nada se escribe en `.out-of-scope/`, porque es una funcionalidad construida, no una rechazada, y registrarla allí contaminaría las comprobaciones de duplicados.
Error rechazado	Explicación amable, luego cerrar.
Mejora rechazada	Un archivo en `.out-of-scope/`, enlazado desde el comentario de cierre, luego cerrar.

.out-of-scope/ es un archivo Markdown por concepto rechazado, no por issue, escrito como documento corto de diseño en lugar de fila de base de datos: qué se rechazó, por qué, y cada issue que lo ha pedido. triage lee todo el directorio antes de evaluar nada, y empareja por concepto en lugar de palabra clave, así “night theme” empareja con dark-mode.md. Cuando encuentra coincidencia muestra la decisión vieja y pregunta si sigues pensando igual, en lugar de re-litigar la solicitud desde cero.

Verifica antes de informar

Antes de cualquier interrogatorio, triage comprueba que la afirmación realmente se sostiene. Para un error, lo reproduce desde los pasos de quien reportó. Para un PR, baja la rama y ejecuta las pruebas relevantes. Luego informa cuál de tres cosas ocurrió: confirmado, con la ruta de código; no se pudo reproducir; o sin detalle suficiente para intentarlo, que es en sí la señal más fuerte de needs-info.

Ejecuta dos comprobaciones más contra la base de código en la misma pasada: redundancia (¿ya está implementado, buscado por concepto de dominio en lugar de por las palabras de quien reportó?) y rechazo previo (¿.out-of-scope/ ya dijo que no?). Ambas son baratas, y ambas producen un wontfix cuando aciertan.

Todo existe para que un artefacto salga bueno: el informe de agente, el comentario estructurado que se publica cuando un issue pasa a ready-for-agent. Una vez publicado, el informe es el contrato y el reporte original es solo contexto. Los informes se escriben para ser duraderos en lugar de precisos, porque un issue puede quedar en ready-for-agent semanas mientras el código se mueve debajo. Así que nombran tipos, firmas y contratos de comportamiento, y nunca rutas de archivos ni números de línea. Una reproducción confirmada produce un informe mucho más fuerte que una suposición.

Un PR es un issue con código adjunto

Donde el gestor trata los pull requests externos como superficie de solicitud, pasan por la misma máquina, con las mismas categorías, mismos estados, mismas transiciones. Los estados solo se leen contra el diff: ready-for-agent significa que hay un informe adjunto y un agente debería dar el siguiente paso sobre el código, ready-for-human significa que está listo para que una persona lo fusione. Un informe en un PR describe lo que falta por hacer al diff existente, no cómo construir la cosa desde cero.

El descubrimiento solo muestra PR externos, porque la rama en curso de un colaborador no es trabajo de triaje. Ese filtro es solo de descubrimiento, y nombrar un PR explícitamente hace que se trie aunque lo haya escrito quien sea. Un borde áspero: el comando de listado de PR externos de la plantilla de GitHub pide a gh pr list un campo authorAssociation que gh no expone, así que el comando tal como está escrito falla directamente (#468).

Preguntas comunes

Ejecuté /to-spec y /to-tickets, y ahora esos tickets están ahí sin triar. ¿Ejecuto /triage sobre ellos? No. Ya están listos para agentes, porque to-tickets aplica la etiqueta ready-for-agent al publicar, justo para que un ejecutor AFK los tome sin otra pasada. El usuario que se topó con esto había corrido el flujo de spec, vio needs-triage en la salida, y encontró que su ejecutor AFK ignoraba todo. triage es la rampa de entrada para trabajo que llega desde fuera; el flujo de spec es el carril para trabajo que originas tú. Se encuentran en ready-for-agent, no antes.

¿Sigue siendo relevante triage ahora que hay un flujo to-spec → to-tickets → implement? Solo si tienes trabajo entrante. triage es anterior a esa columna y hace otro trabajo: es el carril para reportes que otras personas registraron. Si todo en tu gestor salió de tu propia planificación, rara vez lo abrirás. Si mantienes algo público, o tu equipo te registra errores, es la puerta principal. El uso principal es repositorios abiertos que reciben issues de colaboradores externos.

El agente intentó aplicar ready-for-agent y gh dijo que la etiqueta no existe. Error abierto conocido (#616). setup-matt-pocock-skills escribe el vocabulario de etiquetas en docs/agents/triage-labels.md, pero no crea las etiquetas en tu gestor. Crea tú mismo las cinco etiquetas de estado y las dos de categoría, una vez, con gh label create o la UI del gestor, y se acaba. Hay una rama comunitaria con corrección enlazada desde el issue que no se ha fusionado.

Cinco estados no bastan: ¿qué pasa con bloqueado, o diferido, o implementado? Esta es la laguna más registrada de la habilidad, en tres formas. Un issue totalmente especificado pero esperando a que cierre otro issue (#139), donde la queja de quien reportó fue que ready-for-agent es “técnicamente cierto” allí pero engañoso, así que un agente lo toma y choca con un muro. Trabajo futuro condicionado a disparador que está previsto pero aún no es accionable (#297). Y un estado terminal para “implementado, pendiente de verificación”, sin el cual un ejecutor AFK puede reencolar tickets terminados. Matt ha aceptado que el caso bloqueado es real y está indeciso sobre el nombre (blocked frente a paused). Nada de eso se ha publicado. La solución que usa la gente es una etiqueta extra local del repositorio junto a la categoría, que mantiene el estado canónico ocupado por algo honesto al costo de que la habilidad no lo conozca. Un derivado comunitario va más lejos, añadiendo needs-slicing, tracking y etiquetas de esfuerzo. Eso funciona, pero es suyo, no de la habilidad.

¿En qué se diferencia de /diagnosing-bugs? El paso de verificación aquí es deliberadamente superficial (suficiente para responder “¿esto es real, y más o menos dónde vive”), no para hallar causa raíz. Cuando un error no se reproduce desde los pasos de quien reportó en pocos minutos, el movimiento honesto es needs-info, o diagnosing-bugs si quieres perseguirlo ahora. Ningún texto de las habilidades menciona actualmente a la otra; un usuario encontró esa costura, y sigue abierta.

¿Puedo apuntarla a todos mis pendientes y dejarla correr? Puedes pedirlo, pero mira lo que lee. La pasada de “mostrar lo que necesita atención” es un listado barato pensado para selección, donde eliges uno, y luego reúne contexto completo sobre el que elegiste. Ejecútala sobre veinte issues a la vez y un agente puede silenciosamente usar ese listado barato como base de evidencia, que devuelve cuerpos de issues pero no comentarios. Un usuario se topó justo con esto: tres issues ya llevaban un comentario que decía “ya corregido, recomiendo cerrar”, y los tres recibieron informes nuevos de agente. Si quieres una pasada masiva, di explícitamente que los comentarios deben leerse por issue.

¿Funciona con Linear, o con algo que no sea GitHub Issues? Sí, el gestor es configuración, no un supuesto fijo, y la gente lo ejecuta contra Linear (vía el CLI linear), GitLab, y archivos Markdown planos bajo .scratch/. Una división común es Linear para issues y planificación, GitHub para código y PR: las habilidades que dicen “gestor de pendientes” mapean a Linear, las que dicen “PR” mapean a GitHub. En el gestor local de Markdown hay un error abierto de plantilla donde el archivo generado puede llevar los criterios de aceptación dos veces, una en el nivel superior y otra dentro del informe de agente (#200).

Funciona si

Cada elemento que toca termina con exactamente un rol de categoría y un rol de estado, nunca cero, nunca dos estados en conflicto.
Te da una recomendación con razonamiento y se detiene, en lugar de reetiquetar y seguir.
El error se reprodujo, o el PR se bajó y se ejecutó, antes de que nada llegara a ready-for-agent.
Los informes que escribe nombran tipos y comportamientos, y no contienen rutas de archivos ni números de línea.
Una solicitud rechazada hace seis meses vuelve, y la cita y reproduce la razón vieja en lugar de triarla de nuevo.
Cada comentario que publica abre con > *This was generated by AI during triage.*

Dónde encaja

triage es una rampa de entrada, no un paso en la cadena principal. El flujo principal va desde una idea que tuviste (interrogatorio, spec, tickets, implementación, revisión), y triage es el carril paralelo para trabajo que llegó en su lugar. Se fusiona en el mismo lugar: un issue etiquetado ready-for-agent con un informe encima, que implement recoge exactamente como recogería un ticket de to-tickets. Cuando una solicitud necesita afilarse antes de poder informarse, triage ejecuta interrogatorio y domain-modeling juntos, una ronda de preguntas a la vez, para que las decisiones caigan en CONTEXT.md y los ADR a medida que se toman. Cuando no estés seguro en qué carril estás, ask-matt te dirige.