mattpocock/wayfinder

Ha llegado una idea difusa, demasiado grande para una sola sesión de agente, y envuelta en niebla: el camino desde aquí hasta el destino aún no es visible. Wayfinding consiste en encontrar ese camino, no en lanzarse hacia el destino. Esta habilidad traza el camino como un mapa compartido en el gestor de incidencias del repositorio, y luego trabaja sus tickets de decisión (preguntas cuya resolución es una decisión, no fragmentos de una construcción a ejecutar) uno a uno hasta que la ruta esté clara.

El destino varía según el esfuerzo, y nombrarlo es el primer acto de trazado: da forma a cada ticket. Puede ser una especificación para entregar e iterar, una decisión que cerrar antes de comenzar la planificación, o un cambio realizado en el lugar, como una migración de estructura de datos. El mapa es independiente del dominio: trabajo de ingeniería, contenido de curso, cualquier cosa que se ajuste a la forma.

Planificar, no hacer

Wayfinder es planificación por defecto: cada ticket resuelve una decisión, y el mapa está completo cuando el camino está claro, sin que quede nada por decidir antes de que alguien vaya y haga el trabajo. La tentación de simplemente hacer el trabajo suele ser la señal de que has llegado al borde del mapa y es momento de entregar. Un esfuerzo puede anular esto en sus Notas, llevando la ejecución al propio mapa, pero en ausencia de ello, produce decisiones, no entregables.

Referir por nombre

Cada mapa y ticket es una incidencia, por lo que tiene un nombre: su título. En todo lo que el humano lee (narración, las Decisiones hasta ahora del mapa), refiérete a él por ese nombre, nunca por una ID, número o slug desnudo. Un muro de #42, #43, #44 es ilegible; los nombres se leen de un vistazo. La ID y la URL no desaparecen; un nombre envuelve su enlace, pero viajan dentro del nombre, nunca lo reemplazan.

El Mapa

El mapa es una única incidencia en el gestor de incidencias de este repositorio, etiquetada wayfinder:map, el artefacto canónico. Sus tickets son incidencias hijas del mapa.

El mapa es un índice, no un almacén. Enumera las decisiones tomadas y señala los tickets que contienen sus detalles; una decisión vive en un solo lugar, su ticket, por lo que el mapa nunca la repite, solo la resume y la enlaza.

Dónde viven físicamente el mapa, sus tickets hijos, el bloqueo y las consultas de frontera depende del gestor. El gestor de incidencias debería haberte sido proporcionado. Si no es así, dile al usuario que ejecute /setup-matt-pocock-skills. Consulta la sección "Operaciones de wayfinding" del documento del gestor para saber cómo este repositorio las expresa. Si no se ha proporcionado ningún gestor, utiliza por defecto el gestor de markdown local.

El cuerpo del mapa

Todo el mapa a baja resolución, cargado una vez por sesión. Los tickets abiertos no se enumeran: son incidencias hijas abiertas, encontradas mediante consulta.

## Destino

<cómo se ve llegar al final de este mapa: la especificación, decisión o cambio que este esfuerzo busca encontrar su camino. Una o dos líneas; cada sesión se orienta a ello antes de elegir un ticket.>

## Notas

<dominio; habilidades que cada sesión debe consultar; preferencias establecidas para este esfuerzo>

## Decisiones hasta ahora

<!-- el índice: una línea por ticket cerrado, suficiente para juzgar relevancia, luego amplía el enlace para el detalle que contiene el ticket -->

- [<título del ticket cerrado>](enlace): <resumen de una línea de la respuesta>

## Aún no especificado

<!-- ver "Niebla de guerra": niebla dentro del alcance que aún no puedes ticketizar; se gradúa a medida que avanza la frontera -->

## Fuera del alcance

<!-- ver "Fuera del alcance": trabajo descartado más allá del destino; cerrado, nunca se gradúa -->

Tickets

Cada ticket es una incidencia hija del mapa; la ID de la incidencia del gestor es su identidad. Su cuerpo es la pregunta, dimensionada para una sesión de agente de 100 mil tokens:

## Pregunta

<la decisión o investigación que resuelve este ticket>

Cada ticket lleva una etiqueta wayfinder:<tipo>, una de research, prototype, grilling, task (ver Tipos de Ticket).

Una sesión reclama un ticket asignándoselo al desarrollador que conduce el mapa, primero, antes de cualquier trabajo, para que las sesiones concurrentes lo eviten. Ese asignado es el reclamo: un ticket abierto y no asignado no está reclamado.

El bloqueo utiliza la relación de dependencia nativa del gestor: es esencial porque representa la frontera visualmente en la propia interfaz de usuario del gestor, para que el humano vea qué se puede tomar sin abrir el mapa. Solo un gestor que carezca de bloqueo nativo recurre a una convención en el cuerpo. Un ticket está desbloqueado cuando todos los tickets que lo bloquean están cerrados; la frontera son los hijos abiertos, desbloqueados y no reclamados, el borde de lo conocido.

La respuesta no es parte del cuerpo; se registra en la resolución (ver Trabajar a través del mapa). Los activos creados mientras se resuelve un ticket se enlazan desde la incidencia, no se pegan en ella.

Tipos de Ticket

Cada ticket es HITL (humano en el circuito, trabajado con un humano que habla por sí mismo) o AFK, impulsado solo por el agente. Un ticket HITL solo se resuelve a través de ese intercambio en vivo; el agente nunca reemplaza el lado humano (un agente de discusión que responde sus propias preguntas ha roto esto).

• Research (AFK): Leer documentación, APIs de terceros o recursos locales como bases de conocimiento para descubrir un hecho del que depende una decisión. Resuelto por un subagente que llama a la herramienta Skill con "research". Úsalo cuando se requiera conocimiento fuera del directorio de trabajo actual.
• Prototype (HITL): Aumentar la fidelidad de la discusión creando un artefacto barato, tosco y concreto para reaccionar (un esquema, un borrador, un stub o código de UI/lógica) llamando a la herramienta Skill con "prototype". Enlaza el prototipo como un activo. Úsalo cuando "cómo debería verse" o "cómo debería comportarse" sea la pregunta clave.
• Grilling (HITL): Conversación. El caso por defecto. Siempre llama a la herramienta Skill dos veces, para "grilling" y "domain-modeling".
• Task (HITL o AFK): Trabajo manual que debe ocurrir antes de que se pueda tomar una decisión: nada que decidir, prototipar o investigar, pero la discusión está bloqueada hasta que esté hecho. Registrarse en un servicio para que se pueda juzgar su API, aprovisionar acceso, mover datos para que se pueda ver su forma. Este es el único tipo que hace en lugar de decidir, y se gana su lugar al desbloquear una decisión, no al entregar el destino. El agente lo impulsa solo cuando puede (AFK); en caso contrario, entrega al humano una lista de verificación precisa (HITL). Resuelto cuando el trabajo está hecho; la respuesta registra lo que se hizo y cualquier hecho resultante (ubicación de credenciales, nuevas URLs, recuentos de filas) del que dependan tickets posteriores.

Niebla de guerra

El mapa es deliberadamente incompleto: no traces lo que aún no puedes ver. Más allá de los tickets vivos se encuentra la niebla de guerra: la visión borrosa de decisiones e investigaciones que sabes que se avecinan pero que aún no puedes precisar, porque dependen de preguntas aún abiertas. Resolver un ticket despeja la niebla que tiene delante, graduando lo que ahora es especificable en nuevos tickets, uno a la vez, hasta que el camino hacia el destino esté claro y no queden tickets.

La sección Aún no especificado del mapa es donde se escribe esa visión borrosa: la pregunta sospechada, el área a revisitar más tarde. Es la frontera no descubierta hacia el destino: todo aquí está dentro del alcance, pero no lo suficientemente nítido para ticketizarlo. Escríbelo tan libre o tan completo como la vista lo permita; funciona como un letrero para los colaboradores que lean hacia dónde se dirige el esfuerzo.

¿Niebla o ticket? La prueba es si puedes enunciar la pregunta con precisión ahora, no si puedes responderla ahora.

• Ticket cuando la pregunta ya es nítida, incluso si está bloqueada y aún no puedes actuar sobre ella.
• Aún no especificado cuando no puedes formularla con esa nitidez. No precortes la niebla en piezas del tamaño de un ticket: es más tosca que un ticket, y un parche puede graduarse en varios tickets, o ninguno, una vez que la frontera lo alcanza.

Aún no especificado excluye lo que ya está decidido (Decisiones hasta ahora), lo que ya es un ticket vivo y lo que está fuera del alcance (la siguiente sección).

Fuera del alcance

La niebla solo se acumula hacia el destino. El destino fija el alcance, por lo que el trabajo más allá de él está fuera del alcance: no es niebla y no pertenece a Aún no especificado. Tiene su propia sección Fuera del alcance en el mapa: trabajo que has descartado conscientemente de este esfuerzo. El alcance, no la nitidez, lo coloca aquí.

El trabajo fuera del alcance nunca se gradúa (la frontera se detiene en el destino), por lo que regresa solo si el destino se redibuja, y entonces como un esfuerzo nuevo, no una reanudación.

Descartar algo como fuera del alcance es un acto de definición de alcance, no un paso en la ruta. Cuando un ticket que ya existe resulta estar más allá del destino (mal definido en el alcance durante el trazado, o expuesto por una resolución), ciérralo (un ticket cerrado está inequívocamente fuera de la frontera) y deja una línea en la sección Fuera del alcance: el resumen más por qué está fuera del alcance, enlazando el ticket cerrado. Se mantiene fuera de Decisiones hasta ahora, que registra la ruta realmente recorrida; un límite de alcance no es un paso en ella.

Invocación

Dos modos. En cualquier caso, nunca resuelvas más de un ticket por sesión, con la excepción de los tickets de investigación.

Trazar el mapa

El usuario invoca con una idea difusa.

1. Nombra el destino. Llama a la herramienta Skill dos veces, para "grilling" y "domain-modeling", para precisar hacia qué está encontrando su camino este mapa: la especificación, decisión o cambio. El destino fija el alcance, por lo que se resuelve primero.
2. Traza la frontera. Vuelve a hacer "grilling", esta vez en anchura: explora todo el espacio en lugar de profundizar en un solo hilo, sacando a la superficie las decisiones abiertas y los primeros pasos que se pueden dar ahora. Si esto no revela niebla (el camino hacia el destino ya está claro, todo el viaje es lo suficientemente pequeño para una sesión), no necesitas un mapa. Detente y pregúntale al usuario cómo le gustaría proceder.
3. Crea el mapa (etiqueta wayfinder:map): Destino y Notas completados, Decisiones hasta ahora vacías, la niebla esbozada en Aún no especificado.
4. Crea los tickets que puedes especificar ahora como incidencias hijas del mapa, luego conecta los bordes de bloqueo en una segunda pasada (las incidencias necesitan IDs antes de poder referenciarse entre sí). La conexión los ordena en la frontera y los bloqueados; todo lo que aún no puedes especificar permanece en la niebla: la sección Aún no especificado.
5. Ejecuta los subagentes de investigación. Para cada ticket research que acabas de crear, inicia un subagente que llame a la herramienta Skill con "research" para resolverlo en paralelo, capturando sus hallazgos en una rama temporal research/<nombre> con un puntero de contexto desde el ticket.
6. Detente: trazar es trabajo de una sesión; no resuelve nada manualmente.

Trabajar a través del mapa

El usuario invoca con un mapa (URL o número). Un ticket es opcional: sin uno, eliges la siguiente decisión, no el usuario.

1. Carga el mapa: la vista de baja resolución, no todos los cuerpos de los tickets.
2. Elige el ticket. Si el usuario nombró uno, úsalo. En caso contrario, toma el primer ticket de la frontera en orden. Reclámalo: asígnatelo a ti mismo antes de cualquier trabajo.
3. Resuélvelo. Amplía según sea necesario: obtén el cuerpo completo de cualquier ticket relacionado o cerrado bajo demanda; llama a la herramienta Skill para las habilidades que nombre el bloque ## Notas. Si tienes dudas, llama a la herramienta Skill dos veces, para "grilling" y "domain-modeling".
4. Registra la resolución: publica la respuesta como un comentario de resolución, cierra la incidencia y añade un puntero de contexto a la sección Decisiones hasta ahora del mapa.
5. Añade los tickets recién surgidos (crear y luego conectar); gradúa cualquier niebla que la respuesta haya hecho especificable, eliminando cada parche graduado de Aún no especificado para que viva solo como su nuevo ticket. Si la respuesta revela que un ticket (este u otro) está más allá del destino, descartado como fuera del alcance en lugar de resolverlo en la ruta. Si la decisión invalida otras partes del mapa, actualiza o elimina esos tickets.

El usuario puede ejecutar tickets desbloqueados en paralelo, así que espera que otras sesiones editen el gestor concurrentemente.