triage

name	triage
description	Mueve issues y PRs externas por una máquina de estados de roles de triage — categorizar, verificar, entrevistar si hace falta y escribir briefs listos para agentes.
disable-model-invocation	true

Triage

Mover los issues del issue tracker del proyecto a través de una pequeña máquina de estados de roles de triage.

Si este repo trata las pull requests externas como superficie de solicitudes (ver la configuración del issue tracker), el triage también las cubre: una PR es un issue con código adjunto — mismos roles, mismos estados, misma máquina, con unos pocos deltas marcados "para una PR" abajo. Resolver un #42 a secas a issue o PR según la configuración del tracker.

Cada comentario o issue publicado en el issue tracker durante el triage debe empezar con este descargo:

> *This was generated by AI during triage.*

Documentos de referencia

• brief-para-agente.md — cómo escribir briefs durables para agentes
• fuera-de-alcance.md — cómo funciona la base de conocimiento .out-of-scope/

Roles

Dos roles de categoría:

• bug — algo está roto
• enhancement — feature nueva o mejora

Cinco roles de estado:

• needs-triage — el maintainer necesita evaluar
• needs-info — a la espera de más información del reportante
• ready-for-agent — completamente especificado, listo para un agente AFK
• ready-for-human — necesita implementación humana
• wontfix — no se va a actuar sobre él

Para una PR, los mismos estados se leen contra el código adjunto: ready-for-agent significa que hay un brief adjunto y un agente debe dar el siguiente paso sobre el diff; ready-for-human significa que está lista para que un humano la mergee.

Cada issue triado debe llevar exactamente un rol de categoría y un rol de estado. Si los roles de estado entran en conflicto, marcarlo y preguntar al maintainer antes de hacer nada más.

Estos son nombres canónicos de roles — las cadenas de labels reales usadas en el issue tracker pueden diferir. El mapeo debería estar ya configurado — si no, preguntar al maintainer cómo se llaman sus labels.

Transiciones de estado: un issue sin label normalmente va primero a needs-triage; desde ahí pasa a needs-info, ready-for-agent, ready-for-human o wontfix. needs-info vuelve a needs-triage cuando el reportante responde. El maintainer puede sobreescribir en cualquier momento — marcar las transiciones que parezcan inusuales y preguntar antes de proceder.

Invocación

El maintainer invoca /triage y describe lo que quiere en lenguaje natural. Interpretar la petición y actuar. Ejemplos:

• "Muéstrame lo que necesite mi atención"
• "Veamos el #42" (issue o PR)
• "Mueve el #42 a ready-for-agent"
• "¿Qué está listo para que lo tomen los agentes?"

Mostrar lo que necesita atención

Consultar el issue tracker y presentar tres cubetas, lo más antiguo primero:

1. Sin label — nunca triado.
2. needs-triage — evaluación en curso.
3. needs-info con actividad del reportante posterior a las últimas notas de triage — necesita re-evaluación.

Cuando las PRs estén en alcance, incluir las PRs externas en estas cubetas y etiquetar cada línea [PR] o [issue]. El descubrimiento saca a la superficie solo PRs externas (la configuración del tracker define quién cuenta como externo) — la PR en curso de un colaborador no es trabajo de triage. Este filtro es solo para el descubrimiento; una PR nombrada explícitamente siempre se tría, sea de quien sea.

Mostrar conteos y un resumen de una línea por ítem. Dejar que el maintainer elija.

Triar un issue o PR específico

1. Reunir contexto. Leer el issue o PR completo (cuerpo, comentarios, labels, autor, fechas; para una PR, también el diff). Analizar las notas de triage previas para no re-preguntar cuestiones resueltas. Explorar el codebase usando el glosario de dominio del proyecto, respetando los ADRs del área. Ejecutar dos comprobaciones contra el codebase: (a) redundancia — buscar una implementación existente del comportamiento solicitado por concepto de dominio (no solo por la literalidad de la petición), y reportar dónde se buscó. Si se encuentra, es un wontfix de ya-implementado (paso 5). (b) rechazo previo — leer .out-of-scope/*.md y sacar a la superficie cualquiera que se parezca a esta petición.

2. Recomendar. Decir al maintainer la recomendación de categoría y estado con el razonamiento, más un resumen breve del codebase relevante a la petición — incluyendo si ya está implementado. Esperar dirección.

3. Verificar el claim. Antes de cualquier entrevista, comprobar que el claim se sostiene. Para un bug, reproducirlo desde los pasos del reportante. Para una PR, confirmar que el diff hace lo que dice — hacer checkout, ejecutar los tests o comandos relevantes. Reportar qué pasó: confirmado (con el code path), falló, o detalle insuficiente (una señal fuerte de needs-info). Una verificación confirmada produce un brief de agente mucho más fuerte.

4. Entrevistar (si hace falta). Si la petición necesita desarrollarse, ejecutar juntos los skills /grilling y /domain-modeling — darle forma una pregunta por vez, afilando los términos de dominio y actualizando CONTEXT.md/ADRs en línea a medida que aterrizan las decisiones.

5. Aplicar el resultado:

   • ready-for-agent — publicar un comentario con el brief de agente (brief-para-agente.md).
   • ready-for-human — misma estructura que un brief de agente, pero anotando por qué no puede delegarse (juicios de valor, acceso externo, decisiones de diseño, testing manual).
   • needs-info — publicar notas de triage (plantilla abajo).
   • wontfix — cerrar, con el comentario dependiendo del porqué:
     • Ya implementado — el cambio ya existe en el codebase. Señalar dónde vive; no escribir en .out-of-scope/ (esa KB es para peticiones , no construidas).

Cambio rápido de estado

Si el maintainer dice "mueve el #42 a ready-for-agent", confiar en él y aplicar el rol directamente. Confirmar lo que se está a punto de hacer (cambios de rol, comentario, cierre), y actuar. Saltarse la entrevista. Si se mueve a ready-for-agent sin una sesión de entrevista, preguntar si quiere que se escriba un brief de agente.

Plantilla de needs-info

## Triage Notes

**Lo que hemos establecido hasta ahora:**

- punto 1
- punto 2

**Lo que aún necesitamos de ti (@reporter):**

- pregunta 1
- pregunta 2

Capturar todo lo resuelto durante la entrevista bajo "establecido hasta ahora" para que el trabajo no se pierda. Las preguntas deben ser específicas y accionables, no "por favor da más información".

Retomar una sesión previa

Si existen notas de triage previas en el issue o PR, leerlas, comprobar si el reportante ha respondido alguna pregunta pendiente y presentar un panorama actualizado antes de continuar. No re-preguntar cuestiones resueltas.