mattpocock/wayfinder

Une idée floue est arrivée, trop grande pour une seule session d’agent, et enveloppée de brouillard : le chemin d’ici à la destination n’est pas encore visible. Le wayfinding consiste à trouver ce chemin, pas à foncer vers la destination. Cette compétence trace le chemin sous forme d’une carte partagée sur le gestionnaire de tickets du dépôt, puis traite ses tickets de décision (des questions dont la résolution est une décision, et non des morceaux d’exécution à réaliser) un par un jusqu’à ce que la route soit claire.

La destination varie selon l’effort, et la nommer est le premier acte de cartographie : elle façonne chaque ticket. Il peut s’agir d’une spécification à remettre et à itérer, d’une décision à verrouiller avant la planification, ou d’un changement effectué sur place comme une migration de structure de données. La carte est indépendante du domaine : travail d’ingénierie, contenu de cours, tout ce qui s’y prête.

Planifier, pas faire

Wayfinder est par défaut un outil de planification : chaque ticket résout une décision, et la carte est terminée lorsque le chemin est clair, sans rien à décider avant que quelqu’un ne passe à l’action. L’envie de simplement faire le travail est généralement le signe que vous avez atteint le bord de la carte et qu’il est temps de passer la main. Un effort peut outrepasser cela dans ses Notes, en intégrant l’exécution dans la carte elle-même, mais en l’absence de cela, produisez des décisions, pas des livrables.

Référencer par le nom

Chaque carte et chaque ticket est un ticket, donc il a un nom : son titre. Dans tout ce que l’humain lit (narration, les Décisions jusqu’ici de la carte), référez-vous à ce nom, jamais par un simple identifiant, numéro ou slug. Un mur de #42, #43, #44 est illisible ; les noms se lisent d’un coup d’œil. L’identifiant et l’URL ne disparaissent pas ; un nom encapsule son lien, mais ils se trouvent à l’intérieur du nom, sans jamais le remplacer.

La Carte

La carte est un ticket unique sur le gestionnaire de tickets de ce dépôt, étiqueté wayfinder:map, l’artefact canonique. Ses tickets sont des tickets enfants de la carte.

La carte est un index, pas un stockage. Elle liste les décisions prises et pointe vers les tickets qui contiennent leurs détails ; une décision vit dans un seul endroit, son ticket, donc la carte ne la reformule jamais, elle en donne seulement le résumé et le lien.

L’emplacement physique de la carte, de ses tickets enfants, du blocage et des requêtes de frontière dépend du gestionnaire de tickets. Le gestionnaire de tickets devrait vous avoir été fourni. Si ce n’est pas le cas, dites à l’utilisateur d’exécuter /setup-matt-pocock-skills. Consultez la section « Opérations de wayfinding » du document du gestionnaire pour savoir comment ce dépôt les exprime. Si aucun gestionnaire n’a été fourni, utilisez par défaut le gestionnaire local-markdown.

Le corps de la carte

La carte entière en basse résolution, chargée une fois par session. Les tickets ouverts ne sont pas listés : ce sont des tickets enfants ouverts, trouvés par requête.

## Destination

<à quoi ressemble l’atteinte de la fin de cette carte : la spécification, la décision ou le changement vers lequel cet effort trouve son chemin. Une ou deux lignes ; chaque session s’y oriente avant de choisir un ticket.>

## Notes

<domaine ; compétences que chaque session doit consulter ; préférences permanentes pour cet effort>

## Décisions jusqu’ici

<!-- l’index : une ligne par ticket fermé, suffisamment pour juger de la pertinence, puis zoomez sur le lien pour le détail du ticket -->

- [<titre du ticket fermé>](lien) : <résumé d’une ligne de la réponse>

## Pas encore spécifié

<!-- voir « Brouillard de guerre » : brouillard dans le périmètre que vous ne pouvez pas encore ticketiser ; devient ticketisable à mesure que la frontière avance -->

## Hors périmètre

<!-- voir « Hors périmètre » : travail exclu de la destination ; fermé, ne devient jamais ticketisable -->

Tickets

Chaque ticket est un ticket enfant de la carte ; l’identifiant du ticket dans le gestionnaire est son identité. Son corps est la question, dimensionnée pour une session d’agent de 100K tokens :

## Question

<la décision ou l’investigation que ce ticket résout>

Chaque ticket porte une étiquette wayfinder:<type>, parmi research, prototype, grilling, task (voir Types de tickets).

Une session réclame un ticket en l’attribuant au développeur qui pilote la carte, d’abord, avant tout travail, afin que les sessions concurrentes l’évitent. Cet assignataire est la réclamation : un ticket ouvert et non attribué est non réclamé.

Le blocage utilise la relation de dépendance native du gestionnaire : essentiel car il rend la frontière visuellement dans l’interface propre du gestionnaire, afin que l’humain voie ce qui est prenable sans ouvrir la carte. Seul un gestionnaire qui manque de blocage natif revient à une convention de corps. Un ticket est débloqué lorsque tous les tickets qui le bloquent sont fermés ; la frontière est l’ensemble des tickets enfants ouverts, débloqués et non réclamés, le bord du connu.

La réponse ne fait pas partie du corps ; elle est enregistrée lors de la résolution (voir Travailler sur la carte). Les ressources créées lors de la résolution d’un ticket sont liées depuis le ticket, pas collées dedans.

Types de tickets

Chaque ticket est soit HITL (humain dans la boucle, travaillé avec un humain qui parle pour lui-même) soit AFK, piloté par l’agent seul. Un ticket HITL ne se résout que par cet échange en direct ; l’agent ne se substitue jamais au côté humain (un agent de discussion qui répond à ses propres questions a enfreint cette règle).

• Research (AFK) : Lecture de documentation, d’API tierces ou de ressources locales comme des bases de connaissances pour faire émerger un fait dont dépend une décision. Résolu par un sous-agent qui appelle l’outil Skill avec « research ». À utiliser lorsque des connaissances en dehors du répertoire de travail actuel sont nécessaires.
• Prototype (HITL) : Augmenter la fidélité de la discussion en créant un artefact concret, bon marché et grossier pour réagir (un plan, une ébauche, un squelette ou du code UI/logique) en appelant l’outil Skill avec « prototype ». Lie le prototype en tant que ressource. À utiliser lorsque « à quoi cela devrait ressembler » ou « comment cela devrait se comporter » est la question clé.
• Grilling (HITL) : Conversation. Le cas par défaut. Appelez toujours l’outil Skill deux fois, pour « grilling » et « domain-modeling ».
• Task (HITL ou AFK) : Travail manuel qui doit avoir lieu avant qu’une décision ne puisse être prise : rien à décider, prototyper ou rechercher, mais la discussion est bloquée jusqu’à ce que ce soit fait. S’inscrire à un service pour que son API puisse être évaluée, provisionner un accès, déplacer des données pour que leur forme puisse être vue. C’est le seul type qui fait plutôt que de décider, et il gagne sa place en débloquant une décision, pas en livrant la destination. L’agent le pilote seul quand il le peut (AFK) ; sinon, il remet à l’humain une liste de contrôle précise (HITL). Résolu lorsque le travail est fait ; la réponse enregistre ce qui a été fait et tous les faits résultants (emplacement des identifiants, nouvelles URL, nombres de lignes) dont les tickets ultérieurs dépendent.

Brouillard de guerre

La carte est délibérément incomplète : ne cartographiez pas ce que vous ne pouvez pas encore voir. Au-delà des tickets vivants se trouve le brouillard de guerre : la vue floue des décisions et investigations que vous devinez arriver mais que vous ne pouvez pas encore cerner, parce qu’elles dépendent de questions encore ouvertes. Résoudre un ticket dissipe le brouillard devant lui, faisant passer ce qui est désormais spécifiable dans de nouveaux tickets, un à la fois, jusqu’à ce que le chemin vers la destination soit clair et qu’il ne reste plus de tickets.

La section Pas encore spécifié de la carte est l’endroit où cette vue floue est écrite : la question suspectée, le domaine à revoir plus tard. C’est la frontière inexplorée vers la destination : tout ici est dans le périmètre, juste pas assez net pour être ticketisé. Écrivez aussi librement ou aussi complètement que la vue le permet ; cela sert également de repère pour les collaborateurs qui lisent où se dirige l’effort.

Brouillard ou ticket ? Le test est de savoir si vous pouvez énoncer la question précisément maintenant, pas si vous pouvez y répondre maintenant.

• Ticket quand la question est déjà nette, même si elle est bloquée et que vous ne pouvez pas encore agir dessus.
• Pas encore spécifié quand vous ne pouvez pas encore la formuler aussi précisément. Ne prédécoupez pas le brouillard en morceaux de la taille d’un ticket : il est plus grossier qu’un ticket, et une zone peut devenir plusieurs tickets, ou aucun, une fois que la frontière l’atteint.

Pas encore spécifié exclut ce qui est déjà décidé (Décisions jusqu’ici), ce qui est déjà un ticket vivant, et ce qui est hors périmètre (la section suivante).

Hors périmètre

Le brouillard ne se rassemble jamais que vers la destination. La destination fixe le périmètre, donc le travail au-delà est hors périmètre : ce n’est pas du brouillard, et cela n’appartient pas à Pas encore spécifié. Cela a sa propre section Hors périmètre sur la carte : le travail que vous avez consciemment exclu de cet effort. C’est le périmètre, pas la netteté, qui le place ici.

Le travail hors périmètre ne devient jamais ticketisable (la frontière s’arrête à la destination), donc il ne revient que si la destination est redessinée, et alors comme un nouvel effort, pas une reprise.

Exclure quelque chose du périmètre est un acte de cadrage, pas une étape sur la route. Lorsqu’un ticket qui existe déjà s’avère se situer au-delà de la destination (mal cadré pendant la cartographie, ou exposé par une résolution), fermez-le (un ticket fermé est sans ambiguïté hors de la frontière) et laissez une ligne dans la section Hors périmètre : le résumé plus la raison pour laquelle c’est hors périmètre, en liant le ticket fermé. Il reste hors de Décisions jusqu’ici, qui enregistre la route réellement parcourue ; une limite de périmètre n’est pas une étape sur cette route.

Invocation

Deux modes. Dans les deux cas, ne résolvez jamais plus d’un ticket par session, à l’exception des tickets de recherche.

Tracer la carte

L’utilisateur invoque avec une idée floue.

1. Nommez la destination. Appelez l’outil Skill deux fois, pour « grilling » et « domain-modeling », pour définir vers quoi cette carte trouve son chemin : la spécification, la décision ou le changement. La destination fixe le périmètre, donc elle est réglée en premier.
2. Cartographiez la frontière. Discutez à nouveau, en largeur cette fois : explorez tout l’espace plutôt que de creuser une seule piste, en faisant émerger les décisions ouvertes et les premières étapes prenables maintenant. Si cela ne fait émerger aucun brouillard (le chemin vers la destination est déjà clair, tout le voyage assez petit pour une session), vous n’avez pas besoin de carte. Arrêtez-vous et demandez à l’utilisateur comment il souhaite procéder.
3. Créez la carte (étiquette wayfinder:map) : Destination et Notes remplies, Décisions jusqu’ici vides, le brouillard esquissé dans Pas encore spécifié.
4. Créez les tickets que vous pouvez spécifier maintenant en tant que tickets enfants de la carte, puis câblez les arêtes de blocage dans un second passage (les tickets ont besoin d’identifiants avant de pouvoir se référencer mutuellement). Le câblage les trie entre la frontière et les bloqués ; tout ce que vous ne pouvez pas encore spécifier reste dans le brouillard : la section Pas encore spécifié.
5. Lancez les sous-agents de recherche. Pour chaque ticket research que vous venez de créer, lancez un sous-agent qui appelle l’outil Skill avec « research » pour le résoudre en parallèle, en capturant ses résultats sur une branche jetable research/<nom> avec un pointeur de contexte depuis le ticket.
6. Arrêtez-vous : le traçage est le travail d’une session ; il ne résout rien manuellement.

Travailler sur la carte

L’utilisateur invoque avec une carte (URL ou numéro). Un ticket est optionnel : sans un, vous choisissez la prochaine décision, pas l’utilisateur.

1. Chargez la carte : la vue basse résolution, pas le corps de chaque ticket.
2. Choisissez le ticket. Si l’utilisateur en a nommé un, utilisez-le. Sinon, prenez le premier ticket de la frontière dans l’ordre. Réclamez-le : attribuez-le à vous-même avant tout travail.
3. Résolvez-le. Zoomez si nécessaire : récupérez le corps complet de tout ticket lié ou fermé à la demande ; appelez l’outil Skill pour les compétences que le bloc ## Notes nomme. En cas de doute, appelez l’outil Skill deux fois, pour « grilling » et « domain-modeling ».
4. Enregistrez la résolution : publiez la réponse sous forme de commentaire de résolution, fermez le ticket, et ajoutez un pointeur de contexte aux Décisions jusqu’ici de la carte.
5. Ajoutez les tickets nouvellement apparus (créez-puis-câblez) ; faites passer du brouillard désormais spécifiable en tickets, en supprimant chaque zone passée de Pas encore spécifié pour qu’elle ne vive que sous son nouveau ticket. Si la réponse révèle qu’un ticket (celui-ci ou un autre) se situe au-delà de la destination, déclarez-le hors périmètre plutôt que de le résoudre sur la route. Si la décision invalide d’autres parties de la carte, mettez à jour ou supprimez ces tickets.

L’utilisateur peut exécuter des tickets débloqués en parallèle, donc attendez-vous à ce que d’autres sessions modifient le gestionnaire simultanément.