wayfinder y triage: planificar proyectos enormes y ordenar los issues que llegan con un agente

El flujo principal de las skills de Matt Pocock arranca con una idea que cabe en una sesión: la afinas con grill-with-docs, la conviertes en spec y tickets y la construyes. Pero el trabajo no siempre llega así. A veces es un proyecto tan grande y difuso que no sabes ni por dónde empezar. Otras veces llega de fuera: bugs y peticiones que se acumulan en GitHub. wayfinder y triage son las dos rampas de entrada para esos casos, y comparten algo: las dos trabajan sobre tu issue tracker.

Es la décima parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT). Ambas se invocan a mano y necesitan haber ejecutado antes /setup-matt-pocock-skills.

wayfinder: encontrar el camino en la niebla

ask-matt la describe como "el flujo que más exige cognitivamente" del repositorio. Es para un proyecto nuevo o una funcionalidad enorme que no cabe en una sesión y está envuelta en niebla: no se ve el camino desde aquí hasta el destino.

Planificar, no hacer

La primera regla: wayfinder produce decisiones, no entregables. Cada ticket resuelve una pregunta, y el mapa termina cuando el camino está claro y no queda nada por decidir. Las ganas de "ponerse ya a programar" son la señal de que llegaste al borde del mapa y toca pasar el testigo.

El mapa

El mapa es un único issue con la etiqueta wayfinder:map. Es un índice, no un almacén:

## Destination
<qué significa llegar: el spec, la decisión o el cambio buscado>

## Notes
<dominio, skills que cada sesión debe consultar, preferencias>

## Decisions so far
- [Título del ticket cerrado](enlace): resumen de una línea

## Not yet specified
<la niebla: preguntas que se intuyen pero aún no se pueden formular>

## Out of scope
<lo descartado conscientemente, con el motivo>

Los tickets abiertos no aparecen en el mapa: son sub-issues hijos, y la frontera (tickets abiertos, sin bloquear y sin reclamar) se ve en el propio tracker gracias a las relaciones de bloqueo nativas.

Cuatro tipos de ticket

Cada ticket es una pregunta del tamaño de una sesión de unos 100.000 tokens, con una etiqueta de tipo:

Una regla dura: en un ticket con humano, el agente nunca responde por ti. Un agente que se contesta sus propias preguntas rompe la sesión.

La niebla de guerra

El mapa está incompleto a propósito. La prueba para decidir si algo es ticket o niebla no es si puedes responderlo, sino si puedes formular la pregunta con precisión ahora. Si sí, es ticket (aunque esté bloqueado). Si no, va a "Not yet specified" y se convierte en tickets cuando la frontera llega hasta ahí.

Los dos modos

• Trazar el mapa: grilling para fijar el destino, otro grilling en anchura para descubrir la frontera, crear el mapa y los tickets, conectar dependencias en una segunda pasada (los issues necesitan id antes de referenciarse) y lanzar en paralelo los tickets de investigación. Si no aparece niebla, el trabajo no necesita mapa y la skill te lo dice.
• Recorrer el mapa: cargar el mapa, elegir el primer ticket de la frontera, reclamarlo asignándotelo antes de nada, resolverlo según su tipo, publicar la respuesta, cerrarlo, añadir una línea a "Decisions so far" y convertir la niebla que ya se puede formular en tickets nuevos.

Nunca se resuelve más de un ticket por sesión, salvo los de investigación.

Cuando el mapa se despeja

wayfinder entrega, no construye. Cuando el camino está claro, el trabajo entra en el flujo principal por to-spec, que condensa las decisiones enlazadas en un plan construible. Saltar directamente a implement tira todo ese detalle.

triage: una máquina de estados para lo que llega de fuera

triage mueve issues (y, si lo activas, PR externos) por una pequeña máquina de estados. Es solo para trabajo que no creaste tú: los tickets de to-tickets ya salen listos para un agente y no se triagean.

Roles

Dos de categoría (bug y enhancement) y cinco de estado:

Cada issue clasificado lleva exactamente una categoría y un estado. Los nombres reales de las etiquetas se configuran en /setup-matt-pocock-skills.

Cómo trabaja

Le hablas en lenguaje natural: "enséñame lo que necesita mi atención", "veamos el #42", "pasa el #42 a ready-for-agent". Para un issue concreto:

1. Reunir contexto: cuerpo, comentarios, etiquetas, notas de triage anteriores. Dos comprobaciones contra el código: si ya está implementado (buscando por concepto, no por las palabras del issue) y si se rechazó antes (leyendo .out-of-scope/).
2. Recomendar categoría y estado con su razonamiento, y esperar.
3. Verificar: reproducir el bug con los pasos del reporte, o comprobar que el diff de un PR hace lo que dice.
4. Interrogar si hace falta, con grilling y domain-modeling.
5. Aplicar el resultado: un brief para el agente si pasa a ready-for-agent, notas de triage con preguntas concretas si pasa a needs-info, o cierre con explicación si es wontfix.

Todo comentario que publica empieza con "*This was generated by AI during triage.*".

El brief del agente y la memoria de rechazos

El brief es el contrato que seguirá un agente sin supervisión, quizá semanas después. Por eso describe comportamiento e interfaces, no rutas ni números de línea, que caducan, e incluye criterios de aceptación verificables y lo que queda fuera.

Las peticiones rechazadas se guardan en .out-of-scope/, un fichero por concepto (no por issue), redactado como un breve documento de diseño. Cuando llega una petición parecida, triage encuentra el rechazo anterior en lugar de volver a discutirlo.

Cómo se combinan

Las dos alimentan el mismo flujo desde lados opuestos:

• wayfinder crea trabajo desde dentro, cuando el problema es tan grande que hay que descubrir qué decidir. Termina en to-spec.
• triage filtra trabajo que llega de fuera, cuando el problema es separar el ruido de lo que vale la pena. Termina en ready-for-agent, que implement recoge.

Y comparten la base: el issue tracker como estado compartido, el interrogatorio de grilling cuando falta claridad y el glosario para nombrar las cosas igual.

Errores frecuentes

• Usar wayfinder para una funcionalidad bien acotada. Es más lento y denso; para eso está grill-with-docs.
• Resolver varios tickets del mapa en una sesión. Las decisiones pierden contexto.
• Triagear los tickets de to-tickets. Ya son ready-for-agent.
• Briefs con rutas de fichero. Caducan antes de que el agente llegue al issue.

Preguntas frecuentes

¿Funcionan sin GitHub? Sí. Con el tracker local, el mapa es .scratch/<esfuerzo>/map.md y cada ticket un fichero con líneas Type:, Status: y Blocked by:.

¿Pueden trabajar varias sesiones a la vez en un mapa? Sí: el ticket se reclama asignándolo antes de empezar, y la skill espera que otras sesiones editen el tracker en paralelo.

¿triage cubre PR? Solo si activas la opción "PRs as a request surface" en docs/agents/issue-tracker.md. Está desactivada por defecto.

Siguiente paso

Si tienes un proyecto que llevas meses sin empezar porque no sabes por dónde, lanza /wayfinder solo para fijar el destino. En la parte 11 de la guía vemos handoff y to-questionnaire, dos skills para pasar contexto a otro agente o a otra persona.