La habilidad /wayfinder

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

Qué hace

wayfinder toma un esfuerzo demasiado grande para una sesión de agente: una idea cuyo destino puedes nombrar pero cuya ruta aún no ves, y lo traza como un mapa compartido de tickets de decisión en tu gestor de pendientes, luego los resuelve uno a la vez hasta que el camino queda despejado.

Planifica, no hace. Cada ticket contiene una pregunta cuya resolución es una decisión, no un recorte de construcción para ejecutar, y el mapa está terminado cuando no queda nada por decidir antes de que alguien vaya y construya la cosa. Esa regla es lo que separa un ticket de wayfinder de un ticket ordinario de implementación, y es la regla que los agentes rompen más a menudo. Cuando el mapa se despeja, wayfinder entrega; no sigue hacia el código.

Cuándo usarla

La invocas escribiendo /wayfinder; el agente no la usará por su cuenta.

Es el flujo más pesado y denso del conjunto, así que el disparador es estrecho: el esfuerzo tiene que ser genuinamente mayor de lo que una sesión de agente puede contener, y la ruta al destino tiene que estar brumosa. La división es limpia: /grill-with-docs para planificación de una sola sesión, /wayfinder para planificación multisesión.

Lo que tienes delante	Qué ejecutar
Una funcionalidad bien delimitada que puedes acordar de una sentada	grill-me, o grill-with-docs cuando hay base de código
Un proyecto nuevo, o una construcción de muchas sesiones, con la ruta aún poco clara	`/wayfinder`
Un hilo donde la definición ya está hecha	to-spec: sáltate directo el mapa
Un mapa de wayfinder despejado	to-spec, luego to-tickets e implement
Una sesión existente que ya creció demasiado	di “hand off to `/wayfinder`” (handoff sirve de puente hacia un mapa además de fuera de él)

Nuevo no es un requisito. Wayfinder se usa rutinariamente en bases de código heredadas y a medio construir, y podría decirse que es más afilado allí, porque mucha de la bruma es “qué ya es cierto aquí” en lugar de “qué deberíamos hacer”.

Requisitos previos

El mapa y sus tickets viven en el gestor de pendientes del repositorio, así que wayfinder necesita el cableado del gestor que setup-matt-pocock-skills instala. Ese paso escribe una sección “Wayfinding operations” que describe cómo se expresan el mapa, sus tickets hijos, las aristas de bloqueo y las consultas de frontera para GitHub, GitLab o Markdown local. Wayfinder resuelve ese documento a través del puntero en tu CLAUDE.md / AGENTS.md en lugar de una ruta fija; sin ningún gestor configurado recurre a archivos Markdown locales.

El gestor no es decoración. El bloqueo es lo que dibuja la frontera visualmente en la propia UI del gestor, y un gestor sin enlaces nativos de dependencia (un Gitea autoalojado, digamos) degrada wayfinder a inferir bloqueadores desde el texto del mapa, lo que funciona pero necesita supervisión más cercana.

El mapa, la bruma y la frontera

El mapa es un solo issue etiquetado wayfinder:map; sus tickets son sus issues hijos. Es un índice, no un almacén: una decisión vive en exactamente un lugar, su ticket, y el mapa solo la resume y enlaza. Una sesión carga el mapa en baja resolución y amplía tickets individuales bajo demanda, que es lo que permite que un mapa siga creciendo sin que cada sesión pague toda su historia.

Cuatro cosas viven en él:

Destino: cómo se ve llegar al final de este mapa. Nombrarlo es el primer acto de trazar, antes de que exista ningún ticket, porque el destino fija el alcance contra el que se mide cada ticket.
Decisiones hasta ahora: una línea por ticket cerrado, cada una enlazando a donde vive realmente el detalle.
Aún no especificado: la niebla de guerra. Decisiones que se ve que vienen pero aún no se pueden formular con nitidez. La prueba para bruma frente a ticket es si puedes enunciar la pregunta con precisión ahora, no si puedes responderla. Resolver un ticket despeja la bruma delante de él y gradúa lo que ahora sea especificable en tickets nuevos.
Fuera de alcance: trabajo declarado más allá del destino. La bruma solo se reúne hacia el destino, así que el trabajo fuera de alcance se cierra y nunca se gradúa.

La frontera son los tickets abiertos, desbloqueados y sin reclamar (el borde de lo conocido). Una sesión reclama un ticket asignándoselo a sí misma antes de hacer ningún trabajo, así que la persona asignada es la reclamación y las sesiones concurrentes lo saltan. Los tickets se refieren por nombre en todo momento, nunca por un #42 escueto; un muro de números de issue es ilegible en la narración.

Los cuatro tipos de ticket de decisión

Cada ticket lleva una etiqueta wayfinder:<type>, y es HITL (trabajado con un humano que habla por sí mismo) o AFK, conducido solo por el agente. Un ticket HITL solo se resuelve mediante el intercambio en vivo; un agente que responde sus propias preguntas de interrogatorio lo ha roto.

Tipo	Modo	Úsalo cuando	Se resuelve con
`grilling`	HITL	El predeterminado. La pregunta se puede acordar conversando.	interrogatorio más domain-modeling, en una sesión nueva
`prototype`	HITL	“Cómo debería verse” o “cómo debería comportarse”: una pregunta que conversar no puede resolver.	prototype, con el artefacto construido enlazado desde el ticket como recurso
`research`	AFK	Un hecho fuera del directorio de trabajo bloquea una decisión.	Un subagente de research, lanzado al trazar y quemado en paralelo en una rama `research/<name>`
`task`	Cualquiera	Nada que decidir, pero trabajo manual bloquea una decisión, como aprovisionar acceso, registrarse en un servicio, o mover datos para ver su forma.	El agente solo donde pueda, si no una lista precisa para el humano

task es el único tipo que hace en lugar de decidir, y gana su lugar desbloqueando una decisión, nunca entregando una pieza del destino. Este es el tipo que más a menudo sale mal en la práctica: los agentes lo interpretan como un paso de implementación y empiezan a escribir código de producto dentro del mapa.

Research es la única excepción a un ticket por sesión.

Preguntas comunes

¿En qué se diferencia de /grill-with-docs? ¿Con cuál empiezo? Cantidad de sesiones, no tamaño del proyecto. /grill-with-docs es planificación de una sola sesión; wayfinder es planificación multisesión. Si puedes contener todo en una conversación, el interrogatorio es la herramienta más barata y mejor, y wayfinder es genuinamente más lento y denso para ese caso. La taquigrafía comunitaria que se ha asentado: wayfinder solo tiene sentido si el trabajo no cabe en una sola sesión. Esta es por lejos la pregunta más hecha sobre wayfinder, y se sigue haciendo porque las descripciones no te dicen dónde cae tu propia tarea en esa línea. Tienes que juzgar tú mismo la cantidad de sesiones.

Cuando pide el “destino”, ¿significa el final de esta sesión o el final de todo? Todo el mapa. Eso significa el destino de todo el mapa, no solo de la sesión inicial. La pregunta se lee ambigua porque wayfinder es por definición una herramienta multisesión, así que una respuesta de alcance de sesión nunca tiene sentido. Destinos típicos son una spec para entregar, una decisión para fijar antes de empezar a planificar, una prueba de concepto, o un cambio hecho en sitio como una migración de datos.

El mapa está despejado. ¿No escribió wayfinder ya la spec e hizo los tickets? ¿Por qué aún necesito /to-spec y /to-tickets? No. Los tickets de wayfinder son tickets de decisión, y para cuando el mapa cierra todos están cerrados también. Lo que queda es un mapa lleno de decisiones enlazadas, que no es un plan de construcción. to-spec colapsa esas decisiones enlazadas en una spec (/to-spec #<map_issue>) y to-tickets la corta en tickets de implementación bala trazadora. Pasar el mapa directo a implement salta el colapso y desecha el detalle enlazado. Ve directo a implementación solo cuando el esfuerzo resultó genuinamente pequeño. La gente ejecuta la cadena abreviada y cuenta que funciona; los dos pasos extra te compran un artefacto de spec explícito que un revisor o un colega puede leer, lo que importa más cuanto menos en solitario estés.

Mi agente empezó a escribir código de producción en medio de una sesión de wayfinder. El fallo más reportado con esta habilidad, y hay un hueco real detrás. El “planifica, no hagas” predeterminado de wayfinder puede anularse en las Notes del mapa, pero las Notes las escribe el agente, así que la restricción y su exención viven en el mismo archivo que posee la parte restringida. Un usuario vio a un agente escribir “this map carries execution” en sus propias Notes y luego releerlo en sesiones posteriores como su propia licencia, construyendo sobre un servidor vivo. No hay un alto duro en la habilidad para “yo quería lo predeterminado”. Hasta que lo haya: lee las Notes de cualquier mapa que no trazaste tú, mantén la implementación en sus propias sesiones, y trata cualquier wayfinder:task que parezca un recorte de la construcción como mal tipado.

Tracé 27 tickets, y para cuando llegué al decimotercero, el resto ya no tenía sentido. Un resultado real y repetidamente reportado, textual de un reporte de campo. El instinto predeterminado de wayfinder es planificar exhaustivamente, y un mapa cuyos tickets tardíos descansan en supuestos que los tempranos invalidan es justo la trampa de cascada de la que se acusa a la habilidad. Dos cosas lo contrarrestan. Delimita el mapa a un destino acotado en lugar de a todo el producto. Los practicantes cuentan consistentemente que los mapas delimitados a una épica definida se comportan mejor que un extenso “implementar V1”, y planificar algo muy grande no es la meta en primer lugar: publicar incrementos pequeños sí lo es. Y haz prototipo agresivamente: toda la razón por la que la ruta se mantiene vigente es que la incertidumbre se purga con artefactos concretos baratos antes de que la implementación dependa de ella. Wayfinder es “prototypemaxxing”, no “planmaxxing”.

¿Puedo trabajar varios tickets en paralelo? La frontera está construida para mostrarte lo que es tomable, y las aristas de bloqueo están para que el trabajo paralelo sea seguro sobre el papel. En la práctica uno a la vez es el predeterminado más seguro. Usuarios trabajando dos tickets de interrogatorio a la vez reciben en una sesión una pregunta que acaban de responder en la otra, porque las sesiones no comparten contexto. También hay una laguna conocida en tickets de prototipo: se ha reportado un agente construyendo tres variaciones de UI, eligiendo una él mismo, y cerrando el ticket. La selección es tuya, y la habilidad actualmente no lo dice lo bastante alto. Si trabajas en paralelo, revisa tú mismo primero el grafo de dependencias.

¿Tengo que usar GitHub Issues? No. Cualquier gestor de pendientes funciona. GitHub es el camino mejor soportado porque sus sub-issues nativos y relaciones de bloqueo son lo que hace visible la frontera sin abrir el mapa; GitLab, Linear, Jira y Markdown local se usan. Dos advertencias honestas. Un gestor sin bloqueo nativo significa que el grafo de dependencias se infiere del texto y necesita corrección manual. Y Markdown local pone los artefactos en tu repositorio, lo que no se recomienda: guardar este material en el repositorio tiende a llevar a persistencia accidental. Los mantenedores open-source tienen el problema opuesto (gestores públicos llenándose de tickets de planificación generados por agentes) y tienden a elegir Markdown local de todos modos.

El interrogatorio es agotador. Cada pregunta tiene tres párrafos. Esta es la queja viva más aguda sobre wayfinder y no está resuelta. La descomposición que dio un usuario: la verbosidad misma causa agotamiento de decisiones, y la longitud elimina por qué se pregunta algo, así que pierdes la cadena de decisión a decisión a medida que el mapa se alarga. La verbosidad parece una propiedad del conjunto actual de modelos más que de la habilidad, y no ha caído ninguna corrección. Mitigaciones de practicantes en circulación: ejecuta un esfuerzo de razonamiento menor, y pon una instrucción en lenguaje llano en tu CLAUDE.md global. Espera gastar pensamiento real aquí de todos modos, ya que la cantidad de pensamiento que wayfinder te exige no es un defecto sino la mayor parte de para qué sirve.

Una decisión que ya cerré resultó estar mal. ¿Edito el ticket viejo o creo uno nuevo? No hay guía oficial, y el instinto del agente no ayuda: tiende a diseñar alrededor de la mala decisión en lugar de cuestionarla, así que tienes que dirigir a mano. Lo que sí funciona es decirle a wayfinder llanamente qué cambió; actualiza el mapa, revisa los tickets afectados, y comenta en los ya cerrados. Los cambios de alcance a mitad de mapa son recuperables. Un mapa que diseñaste para cambiar es un olor de delimitación.

¿A dónde se fue decision-mapping? Es esta habilidad, renombrada a wayfinder en v1.1 e invocada como /wayfinder. “Decision map” era jerga y además imprecisa, ya que solo uno de los cuatro tipos de ticket es realmente una decisión por sí mismo. El reencuadre dio a la habilidad un vocabulario coherente (destino, niebla de guerra, frontera, el mapa) en lugar de un término inventado encima. La unidad conservó la palabra “decisión”, eso sí: un ticket de decisión es como se llama un ticket de wayfinder, justo para evitar que se lea como ticket de implementación.

Funciona si

El destino está escrito y acordado antes de que exista un solo ticket.
Cada ticket abierto se lee como una pregunta. Cualquier ticket que se lea “construye la X” está mal tipado o pertenece aguas abajo del mapa.
Puedes mirar tu gestor y ver qué tickets son tomables sin abrir el mapa, ya que esa es la frontera dibujándose mediante bloqueo nativo.
Una sesión resuelve un ticket, publica la respuesta como comentario de resolución, lo cierra, y deja una línea en Decisions so far del mapa. Luego se detiene.
Not yet specified se encoge con el tiempo. Un parche de bruma que se gradúa a ticket desaparece de esa sección en lugar de vivir en ambos sitios.
Cuando el interrogatorio inicial en anchura no revela bruma, la habilidad se detiene y te dice que el esfuerzo es lo bastante pequeño para saltarse el mapa.
La sesión que termina el mapa te dirige hacia una spec, no hacia un pull request.

Dónde encaja

wayfinder es una rampa de entrada situacional, no la puerta principal predeterminada. La cadena idea → publicar guiada por interrogatorio sigue siendo donde empieza la mayor parte del trabajo; wayfinder es a lo que subes cuando la idea es demasiado grande para caber en una sesión, y se fusiona de vuelta a esa cadena en to-spec, porque un mapa despejado entrega en lugar de construir.

Debajo, son mayormente otras habilidades con la programación de wayfinder: interrogatorio y domain-modeling resuelven el tipo de ticket predeterminado, prototype resuelve los tickets que conversar no puede, y research corre como subagente para que su lectura nunca caiga en tu sesión. handoff es el puente de entrada y salida: hacia un mapa desde una conversación que se quedó pequeña, fuera de uno cuando aparece una misión secundaria a mitad de sesión. Para cualquier otra cosa, ask-matt dirige por todo el conjunto.