Implementazione e utilizzo della skill Wayfinder

Installazione e configurazione

Per installare e configurare Wayfinder, il primo passo è ottenere il repository ufficiale. Si clona il repository GitHub mattpocock/skills tramite il comando standard:

git clone https://github.com/mattpocock/skills.git

Il repository (che ha raggiunto 160k stelle e 7 milioni di download dalla v1.1) contiene la skill nella struttura skills/engineering/wayfinder/. Il file principale da caricare nel proprio ambiente è SKILL.md, mentre la documentazione estesa si trova in docs/engineering/wayfinder.md all’interno dello stesso repository. Una volta clonato, la skill è pronta per essere importata o referenziata dal proprio tool di sviluppo.

Configurazione dell’issue tracker

Wayfinder è agnostica rispetto al tracker: funziona identicamente con GitHub, GitLab o con semplici file markdown locali. La scelta dipende dal workflow del team e dai vincoli del progetto.

GitHub/GitLab: la mappa e i ticket vivono come issue nel repository. Si consiglia di creare un template per la mappa e per i ticket, così ogni nuovo issue parte con la struttura minima precompilata (nome, tipo, stato, dipendenze). Per la mappa si può usare un’etichetta dedicata (es. wayfinder:map), mentre per i ticket si useranno le label tipologiche descritte sotto.
Markdown locale: se il progetto non usa un tracker remoto, la mappa è un file WAYFINDER.md nella root del repo, e i ticket sono file separati (es. nella cartella .wayfinder/tickets/). In questo caso, il "blocking" si rappresenta con una riga esplicita nel frontmatter di ciascun ticket, che indica gli id dei ticket bloccanti. La "frontier" va dedotta leggendo i file aperti.

Label e convenzioni per i ticket

Ogni ticket deve avere un nome leggibile (mai solo un id numerico — es. "Decidere il formato di export" e non "issue #42"). Il nome è ciò che rende la mappa consultabile a colpo d’occhio.

Le label tipologiche sono obbligatorie per distinguere il tipo di lavoro e il livello di interazione umana:

wayfinder:research — AFK (autonomous, fully agent-driven). Il ticket è risolto da un subagent /research che legge documentazione, API o KB per portare alla luce un fatto. Può essere risolto in blocco (eccezione alla regola "un ticket per sessione").
wayfinder:prototype — HITL (human in the loop). Il ticket richiede un artefatto concreto e grezzo (outline, stub, codice UI/logica), prodotto da /prototype, per alzare la fedeltà della discussione.
wayfinder:grilling — HITL, caso di default. È una conversazione guidata da /grilling e /domain-modeling. L’agente non si sostituisce all’umano: la decisione finale resta sempre umana.
wayfinder:task — HITL o AFK. Lavoro manuale che deve avvenire prima di una decisione (es. firmare un servizio, provisioning, spostare dati).

Oltre alle label, si consiglia di adottare una convenzione di stato sui ticket: open (in coda), claimed (assegnato al dev che lo sta risolvendo), closed (decisione presa e registrata). Lo stato "claimed" è fondamentale: il dev che guida la mappa assegna a sé il ticket prima di iniziare, così le sessioni concorrenti lo saltano automaticamente.

Primo avvio: mappa vuota

Alla prima configurazione, la mappa sarà vuota o con una sola destination. In questo caso, la procedura è:

Nomina la destination — definisci cosa significa "fine della mappa": una spec, una decisione architetturale, un cambiamento di comportamento.
Avvia /grilling e /domain-modeling — questa conversazione iniziale serve a tirare fuori le prime decisioni intuibili (la "fog of war").
Mappa la frontier — identifica i ticket aperti, non bloccati e non claimati: sono il bordo del conosciuto, il punto da cui partire.
Crea la mappa e i ticket — la mappa come issue/file indice, i ticket come issue/file individuali con le label appropriate.
Lancia i subagent research — per i ticket wayfinder:research, si può partire subito, perché non richiedono interazione umana.

Se invece esiste già una mappa (URL o numero), si carica, si sceglie un ticket dalla frontier, lo si claaima, lo si risolve, si registra la decisione nella mappa e si aggiorna lo stato. La mappa si aggiorna a ogni ticket chiuso: si sposta la riga da "Not yet specified" a "Decisions so far", e si aggiungono gli eventuali nuovi ticket emersi dalla nebbia.

Concetti fondamentali della mappa

Il principio del wayfinding è radicalmente diverso da quello di un piano tradizionale: l’obiettivo non è "caricare verso la destinazione", ma trovare la strada mentre si procede. La meta esiste, ma il percorso che porta a essa non è conoscibile in anticipo. Wayfinder formalizza questa idea trasformando il lavoro in una sequenza di decisioni piccole e verificabili, risolte una alla volta. Ogni decisione chiusa schiarisce la nebbia davanti a sé e fa emergere la decisione successiva, che prima non era visibile. È un processo incrementale e iterativo: non si pianifica tutto in anticipo, ma si pianifica solo quanto basta per fare il passo successivo.

Struttura della mappa

La mappa è un artefatto vivo che vive sull’issue tracker del repository. Non è un archivio di dettagli, ma un indice che elenca le decisioni prese e punta ai ticket che contengono il dettaglio. La struttura è composta da cinque sezioni:

Destination — definisce cosa significa raggiungere la fine della mappa: una spec completa, una decisione architetturale, un cambiamento di comportamento. È il criterio con cui si capisce che il lavoro è finito.
Notes — contiene il contesto: il dominio del problema, le skill da consultare, le preferenze del team o del committente. Serve a chiunque apra la mappa per la prima volta.
Decisions so far — l’indice delle decisioni chiuse, una riga per ogni ticket chiuso. È la storia del percorso: mostra cosa è stato deciso e perché. Ogni riga punta al ticket che contiene il dettaglio.
Not yet specified — la "fog of war": decisioni che si intuiscono ma che non sono ancora precisabili. Non si traccia ciò che non si può vedere: questi ticket sono segnalati ma non dettagliati, perché il dettaglio emergerà quando la nebbia si schiarirà.
Out of scope — il lavoro escluso consapevolmente dall’effort. È importante dichiararlo esplicitamente, per evitare che qualcuno lo riscopra e lo reintroduca per sbaglio.

La mappa come artefatto condiviso

La mappa non è uno strumento privato del singolo dev: è un artefatto condiviso che vive sul tracker del repo, visibile a tutto il team. Questo ha due conseguenze pratiche. La prima è che la mappa è il punto di riferimento unico per lo stato del lavoro: chiunque può aprire l’issue della mappa e capire in pochi secondi dove si è, cosa è stato deciso e cosa resta da decidere. La seconda è che la mappa coordina le sessioni concorrenti: se più agenti o più dev lavorano sullo stesso progetto, la mappa e il meccanismo di "claim" dei ticket impediscono che due sessioni risolvano la stessa decisione in parallelo. Il dev che guida la mappa assegna a sé il ticket prima di iniziare, e le altre sessioni lo vedono come "claimed" e lo saltano.

La scelta di far vivere la mappa sull’issue tracker — e non in un documento separato — è deliberata: il tracker ha già le primitive necessarie (issue, label, dipendenze, assegnazione) e le rende visibili nell’UI. Il "blocking" tra ticket usa la relazione nativa di dipendenza del tracker, così la frontier (l’insieme dei ticket aperti, non bloccati e non claimati) è immediatamente leggibile a colpo d’occhio. La mappa è deliberatamente incompleta: non traccia ciò che non può ancora vedere, e questo è un vantaggio, non un limite.

Tipi di ticket e modalità operative

Il sistema di ticket è il cuore operativo di Wayfinder: ogni decisione da prendere viene isolata in un ticket, etichettata con il suo tipo e risolta secondo una modalità specifica. La scelta del tipo non è un dettaglio burocratico, ma determina chi fa cosa, con quale strumento e con quale livello di autonomia. In particolare, la distinzione fondamentale passa tra ticket HITL (human in the loop) e ticket AFK (away from keyboard).

Research ticket (AFK)

Il ticket di ricerca è l’unico caso in cui l’agente lavora in piena autonomia, senza interazione umana. L’obiettivo è portare alla luce un fatto: leggere documentazione, API, knowledge base o codice esistente per rispondere a una domanda concreta e verificabile. Esempi tipici: "Qual è il formato esatto della risposta dell’API X?", "Quali parametri accetta la funzione Y?", "Quali vincoli di licenza si applicano alla libreria Z?".

Il ticket viene risolto da un subagent /research, che opera in modalità AFK. La risoluzione non produce una decisione, ma un input informativo che sblocca i ticket successivi. Per questo motivo, i ticket di ricerca sono l’unica eccezione alla regola "un ticket per sessione": possono essere risolti in blocco, perché non richiedono coinvolgimento umano e non comportano scelte. La loro natura fattuale li rende sicuri da automatizzare: un fatto o è vero o è falso, e il subagent può verificarlo senza bisogno di un giudizio umano.

Prototype ticket (HITL)

Il ticket di prototipo serve ad alzare la fedeltà della discussione. Quando una conversazione astratta rischia di girare a vuoto, si produce un artefatto concreto e grezzo — un outline, uno stub, un frammento di codice UI o logica — che rende tangibile ciò di cui si sta parlando. Il prototipo non deve essere rifinito né completo: deve essere abbastanza buono da far emergere la decisione giusta.

La produzione dell’artefatto è affidata al subagent /prototype, ma la modalità è HITL: il prototipo viene discusso con l’umano, che lo usa come base per decidere. Il valore del prototipo non sta nel codice che produce, ma nella conversazione che sblocca: vedere un’interfaccia grezza fa emergere obiezioni e preferenze che una descrizione testuale non avrebbe mai fatto emergere. Una volta presa la decisione, il prototipo ha esaurito il suo scopo: non è un deliverable, ma uno strumento di chiarificazione.

Grilling ticket (HITL, default)

Il grilling è il caso di default: quando non c’è una ragione specifica per scegliere un altro tipo, si usa questo. È una conversazione guidata, condotta con i comandi /grilling e /domain-modeling, in cui l’agente interroga l’umano per estrarre la decisione.

La caratteristica distintiva del grilling è che l’agente non si sostituisce all’umano: non propone una soluzione e la fa validare, ma fa domande, esplora i vincoli, mette in discussione le assunzioni e porta alla luce le implicazioni delle diverse opzioni. La decisione finale resta sempre umana. Il grilling è il tipo più adatto quando la decisione dipende da preferenze, priorità o compromessi che solo una persona può valutare. È anche il più flessibile: può essere usato sia nelle fasi iniziali (per definire la destination e mappare la fog of war) sia nelle fasi avanzate (per chiudere le ultime decisioni aperte).

Task ticket (HITL o AFK)

Il task copre il lavoro manuale che deve avvenire prima di una decisione. Non è una ricerca (non si cerca un fatto) e non è una conversazione (non si discute): è un’azione concreta che deve essere compiuta perché la decisione successiva diventi possibile. Esempi: firmare un servizio, fare provisioning di un ambiente, spostare dati da un sistema a un altro.

La modalità può essere sia HITL che AFK, a seconda della natura del task. Se l’azione richiede credenziali, autorizzazioni o accessi che solo un umano possiede, è HITL: l’agente prepara tutto il necessario, ma l’esecuzione finale richiede l’intervento umano. Se invece il task è interamente automatizzabile (es. uno script che sposta dati), può essere AFK. La distinzione va dichiarata nel ticket, perché determina chi può claimarlo e come viene risolto.

Differenze tra modalità HITL e AFK

La distinzione HITL/AFK è il criterio che governa l’intero flusso di lavoro. In modalità HITL, l’agente prepara, propone, interroga — ma non decide. Ogni conclusione deve passare dalla validazione umana, e il ticket si chiude solo quando l’umano ha espresso la sua scelta. Questa modalità è obbligatoria per le decisioni che comportano preferenze, compromessi o responsabilità: nessun agente può decidere al posto dell’umano cosa è meglio per il prodotto.

In modalità AFK, l’agente lavora da solo, ma solo su ticket che non comportano scelte: la ricerca di fatti e i task completamente automatizzati. L’AFK è sicuro proprio perché il suo output è verificabile — un fatto è vero o falso, un task è fatto o non è fatto — e non richiede un giudizio umano.

La regola pratica è: se la risoluzione del ticket cambia il corso del progetto, serve HITL; se si limita a raccogliere informazioni o a preparare il terreno, può essere AFK. La scelta della modalità va fatta al momento della creazione del ticket, perché determina il flusso di lavoro, gli strumenti da usare e chi può claimarlo.

Flusso di lavoro con idea vaga

Il flusso di lavoro con un’idea vaga è il caso d’uso più frequente e quello per cui Wayfinder è stato progettato. Si parte da un’intuizione, un problema mal definito o una richiesta generica, e si arriva a una mappa operativa con ticket chiari e una frontier visibile. Il processo si articola in quattro fasi, che possono essere eseguite in sequenza o con iterazioni rapide.

Nominare la destinazione

Il primo passo è dare un nome alla destinazione. Non si tratta di definire il percorso (che è ignoto per definizione), ma di stabilire il criterio con cui si capirà che il lavoro è finito. La destination deve essere una frase concreta e verificabile, non un’aspirazione vaga. Esempi validi: "Spec completa del nuovo endpoint di export", "Decisione architetturale sul sistema di caching", "Cambiamento di comportamento: il form di login usa OAuth2". La destination va scritta nella sezione omonima della mappa e deve essere concordata con il committente o lo stakeholder: se la meta non è condivisa, ogni ticket successivo sarà ambiguo.

In questa fase conviene annotare anche le prime Notes: il dominio del problema, le skill che probabilmente serviranno, le preferenze note del team o del cliente. Le Notes non devono essere esaustive — la mappa è deliberatamente incompleta — ma devono dare a chiunque apra la mappa un contesto minimo per orientarsi.

Chiarire il dominio del problema

Con la destination nominata, si avvia la fase di chiarificazione. Wayfinder prescrive l’uso di /grilling e /domain-modeling: una conversazione guidata in cui l’agente interroga l’umano per estrarre il maggior numero possibile di informazioni sul dominio. L’obiettivo non è risolvere il problema, ma mapparne i contorni: quali sono i vincoli, le entità coinvolte, le relazioni tra loro, i termini del dominio che vanno usati con precisione.

Durante il grilling, l’agente non propone soluzioni: fa domande, esplora le assunzioni, porta alla luce implicazioni che l’umano non aveva considerato. Il domain-modeling, in particolare, serve a far emergere le entità e le loro relazioni — un passo essenziale per capire quali decisioni dovranno essere prese in seguito. Al termine di questa fase, si dovrebbe avere un quadro sufficiente per intuire le prime decisioni, anche se non ancora per dettagliarle.

Creare la mappa iniziale

Con le informazioni raccolte, si crea la mappa. La mappa è un issue (o un file markdown, se si usa un tracker locale) con la struttura standard: Destination, Notes, Decisions so far (vuota all’inizio), Not yet specified e Out of scope. La sezione "Not yet specified" è la più importante in questa fase: contiene le decisioni che si intuiscono ma che non sono ancora precisabili — la "fog of war". Ogni voce in questa sezione è un ticket futuro, ma non va dettagliata: va solo segnalata, perché il dettaglio emergerà quando la nebbia si schiarirà.

Nella sezione Out of scope si annota esplicitamente ciò che è escluso dall’effort. Questo è un passaggio spesso trascurato ma cruciale: dichiarare ciò che non si farà evita che qualcuno lo riscopra più avanti e lo reintroduca per sbaglio, facendo deragliare il lavoro.

La mappa iniziale non deve essere completa: deve essere appena sufficiente per individuare la frontier. Se la sezione "Not yet specified" contiene troppe voci, significa che il grilling non è stato abbastanza approfondito; se ne contiene troppo poche, si rischia di partire senza una direzione chiara. L’equilibrio giusto si trova con la pratica: la mappa si aggiorna a ogni ticket chiuso, quindi l’imperfezione iniziale è accettabile e prevista.

Popolare i decision ticket

L’ultimo passo è trasformare le voci della "fog of war" in ticket individuali. Non tutte le voci diventano ticket subito: solo quelle che sono abbastanza chiare da essere affrontate — cioè quelle che costituiscono la frontier. Le altre restano nella mappa come segnaposto, in attesa che la nebbia si schiari.

Ogni ticket deve avere:

Un nome leggibile — mai solo un id numerico. Il titolo deve dire cosa si sta decidendo ("Decidere il formato di export", non "issue #42").
Una label tipologica — wayfinder:research, wayfinder:prototype, wayfinder:grilling o wayfinder:task, a seconda della natura del lavoro.
Le dipendenze — il blocking va espresso con la relazione nativa del tracker, così la frontier è visibile nell’UI.
Lo stato — open, con la possibilità di passare a claimed quando qualcuno lo prende in carico.

La scelta della label va fatta con criterio, perché determina il flusso di lavoro:

I ticket wayfinder:research (AFK) possono essere lanciati subito, perché non richiedono interazione umana. Se ci sono più ticket di ricerca, possono essere risolti in blocco — è l’unica eccezione alla regola "un ticket per sessione".
I ticket wayfinder:grilling (HITL, default) richiedono una conversazione con l’umano e vanno affrontati uno alla volta.
I ticket wayfinder:prototype (HITL) richiedono la produzione di un artefatto grezzo per alzare la fedeltà della discussione.
I ticket wayfinder:task (HITL o AFK) coprono lavoro manuale che deve avvenire prima di una decisione.

Al termine di questa fase, la mappa è operativa: ha una destination, una lista di decisioni da prendere e una frontier visibile. Il lavoro può iniziare — un ticket alla volta, finché la strada verso la destinazione non è chiara.

Flusso di lavoro con mappa esistente

Quando il lavoro è già stato avviato in una sessione precedente, il punto di partenza non è più un’idea vaga ma una mappa esistente, identificabile da un URL o da un numero. La procedura in questo caso è più snella e si articola in quattro momenti: caricamento della mappa, claim di un ticket, risoluzione e aggiornamento. L’obiettivo è mantenere il ritmo del wayfinding: un ticket alla volta, registrando ogni decisione presa.

Caricare la mappa esistente

Il primo passo è recuperare la mappa dal tracker. Se si lavora su GitHub o GitLab, basta aprire l’issue della mappa tramite URL o numero. Se si usa un tracker locale, si apre il file WAYFINDER.md nella root del repo. Prima di iniziare qualsiasi lavoro, è necessario leggere l’intera mappa — non solo la sezione della frontier — per ricostruire il contesto: la destination, le decisioni già prese in "Decisions so far", le voci in "Not yet specified" e ciò che è stato dichiarato "Out of scope". Questo passaggio è essenziale perché la mappa è l’unica fonte di verità sullo stato del lavoro: chi la apre deve capire in pochi secondi dove si è e cosa resta da fare, senza dover ricostruire la storia da zero.

La lettura della mappa serve anche a verificare che la frontier sia aggiornata. Se si nota una discrepanza — un ticket chiuso ma non registrato, una voce in "Not yet specified" che è già diventata un ticket — va segnalata prima di procedere, perché la mappa deve essere sempre accurata per coordinare correttamente le sessioni concorrenti.

Claimare un ticket

Con la mappa caricata, si individua la frontier: l’insieme dei ticket aperti, non bloccati e non claimati. Da questa lista si sceglie un ticket da risolvere. La scelta non è casuale: si parte dal ticket che sblocca il maggior numero di decisioni successive, oppure da quello che la mappa indica come prioritario. Se un ticket è bloccato da un altro, non è nella frontier e non può essere scelto: va prima risolto il ticket bloccante.

Prima di iniziare qualsiasi lavoro sul ticket, lo si claaima assegnandolo a sé. Il claim è un’operazione esplicita sul tracker: si assegna l’issue al dev che guida la mappa. Questo meccanismo è fondamentale per il coordinamento: una volta claimato, il ticket non è più nella frontier, e le sessioni concorrenti lo vedono come "claimed" e lo saltano. Se due agenti lavorassero sullo stesso ticket in parallelo, rischierebbero di prendere decisioni divergenti e di sprecare lavoro. Il claim impedisce questo scenario con una singola operazione sul tracker.

Risolvere il ticket

Con il ticket claimato, si procede alla risoluzione secondo la modalità indicata dalla label. La regola è tassativa: mai più di un ticket per sessione (l’unica eccezione sono i ticket wayfinder:research, che possono essere risolti in blocco perché non richiedono interazione umana). Questo limite non è burocratico: risolvere un ticket schiarisce la nebbia davanti a esso e fa emergere nuovi ticket che prima non erano visibili. Se si risolvessero più ticket in una sessione, si rischierebbe di prendere decisioni senza avere il contesto emerso dalle decisioni precedenti.

La modalità di risoluzione dipende dal tipo di ticket:

wayfinder:research — si lancia un subagent /research che legge documentazione, API o KB per portare alla luce il fatto richiesto. La risoluzione è un input informativo, non una decisione.
wayfinder:prototype — si produce un artefatto concreto e grezzo (outline, stub, codice UI/logica) tramite /prototype, e lo si discute con l’umano per far emergere la decisione.
wayfinder:grilling — si conduce una conversazione guidata con /grilling e /domain-modeling, interrogando l’umano per estrarre la decisione. L’agente non decide: fa domande, esplora vincoli e implicazioni, e l’umano esprime la scelta finale.
wayfinder:task — si esegue il lavoro manuale richiesto (firmare un servizio, provisioning, spostare dati), in modalità HITL o AFK a seconda della natura del task.

Durante la risoluzione, è importante annotare le informazioni emerse che potrebbero essere utili per i ticket successivi. Non vanno però registrate subito sulla mappa: la registrazione avviene in un momento dedicato, dopo la chiusura del ticket.

Aggiornare la mappa dopo la risoluzione

Una volta presa la decisione, il ticket si chiude e si aggiorna la mappa. Questo passaggio è parte integrante del flusso di lavoro, non un’appendice: la mappa deve riflettere lo stato reale del lavoro, altrimenti perde la sua funzione di coordinamento.

L’aggiornamento prevede quattro operazioni:

Registrare la decisione — si aggiunge una riga in "Decisions so far", con il nome leggibile del ticket e un puntatore al ticket che contiene il dettaglio. La mappa è un indice, non un archivio: la riga deve essere sintetica, perché il dettaglio sta nel ticket.
Spostare la voce in "Not yet specified" — se il ticket chiuso corrispondeva a una voce della fog of war, quella voce si sposta da "Not yet specified" a "Decisions so far". La nebbia si è schiarita davanti a quel punto del percorso.
Aggiungere i nuovi ticket emersi — la risoluzione di un ticket spesso fa emergere nuove decisioni che prima non erano visibili. Queste vanno aggiunte alla mappa, nella sezione appropriata: se sono abbastanza chiare da essere affrontate, diventano ticket nella frontier; altrimenti restano in "Not yet specified" come segnaposto.
Aggiornare lo stato del ticket — il ticket passa da "claimed" a "closed", e si rimuove l’assegnazione. Se il ticket ha sbloccato altri ticket, questi ora entrano nella frontier e sono visibili nell’UI come non bloccati.

Al termine dell’aggiornamento, la mappa riflette il nuovo stato del lavoro: una decisione in più, una nebbia leggermente più schiarita, e una frontier aggiornata con i nuovi ticket emersi. Il ciclo può ricominciare: si sceglie il prossimo ticket dalla frontier, lo si claaima, lo si risolve e si aggiorna la mappa. Così, un ticket alla volta, si procede finché la strada verso la destination non è chiara e non restano ticket aperti.

Gestione della frontier e blocco

La frontier come bordo del conosciuto

La frontier è l’insieme dei ticket aperti, non bloccati e non claimati: rappresenta il bordo del conosciuto, il punto esatto in cui il lavoro può proseguire senza dipendere da decisioni ancora da prendere. È la zona di intervento immediato — ciò che è abbastanza chiaro da essere affrontato ora, senza aspettare che altri ticket vengano risolti.

La frontier non è un concetto statico: si sposta a ogni ticket chiuso. Quando una decisione viene presa, la nebbia davanti a essa si dirada, e nuovi ticket che prima non erano visibili emergono e si aggiungono alla frontier. Il lavoro di wayfinding procede proprio così: si risolve un ticket, la frontier avanza, emergono nuovi ticket, si risolve il successivo. La frontier è il punto di partenza obbligato per ogni sessione di lavoro: si sceglie un ticket dalla frontier, non un ticket qualunque. Questo garantisce che il lavoro proceda sempre nella direzione in cui le informazioni sono sufficienti per decidere, evitando di bloccarsi su decisioni che dipendono da altre non ancora prese.

La visibilità della frontier è uno dei motivi per cui Wayfinder insiste sull’uso dell’issue tracker nativo: la frontier deve essere leggibile a colpo d’occhio, senza dover interrogare nessuno o ricostruire lo stato del lavoro da documenti sparsi. Chi apre la mappa deve vedere immediatamente quali ticket sono pronti per essere affrontati.

Blocking nativo tra ticket

Le dipendenze tra ticket vengono espresse usando la relazione nativa di dipendenza del tracker — in GitHub e GitLab, il meccanismo di "blocks"/"is blocked by" tra issue. Questa scelta ha un vantaggio pratico immediato: la frontier diventa visibile nell’interfaccia del tracker senza bisogno di configurazioni aggiuntive. Un ticket bloccato appare come tale nell’UI, e chiunque può vedere che non è ancora pronto per essere affrontato.

Il blocking non è un dettaglio organizzativo: è ciò che rende la frontier affidabile. Un ticket bloccato non è nella frontier, perché non può essere risolto finché il ticket che lo blocca non viene chiuso. Se si ignorassero le dipendenze, si rischierebbe di iniziare un lavoro che non può essere completato, o peggio, di prendere una decisione senza avere il contesto emerso dalla decisione precedente. La regola operativa è tassativa: se un ticket è bloccato, va prima risolto il ticket bloccante. Solo quando il blocco si scioglie, il ticket entra nella frontier e diventa affrontabile.

L’uso del blocking nativo ha anche un effetto di coordinamento: quando un ticket viene chiuso, i ticket che dipendono da esso si sbloccano automaticamente e appaiono nella frontier. Questo aggiornamento è immediato e visibile a tutti — non richiede comunicazioni manuali né aggiornamenti di stato fuori dal tracker.

Regola di un ticket per sessione

La regola "un ticket per sessione" è il vincolo operativo che tiene insieme l’intero meccanismo del wayfinding. La sua ragione non è burocratica ma epistemica: risolvere un ticket schiarisce la nebbia davanti a esso e fa emergere nuove decisioni che prima non erano visibili. Se si risolvono più ticket in una sola sessione, si prendono decisioni senza avere il contesto che le decisioni precedenti avrebbero portato alla luce. Si rischia di scegliere in base a informazioni incomplete, e di dover tornare indietro a correggere.

L’unica eccezione è il ticket di tipo wayfinder:research: può essere risolto in blocco, perché non comporta una scelta ma la raccolta di un fatto verificabile. Un fatto è vero o falso indipendentemente dalle decisioni circostanti, quindi risolverne più di uno per sessione non introduce il rischio di decisioni basate su contesto mancante. Per tutti gli altri tipi — grilling, prototype, task — la regola è tassativa: un ticket, una sessione, una decisione.

Questa regola ha anche una funzione di ritmo: costringe a procedere per passi piccoli e verificabili, registrando ogni decisione prima di passare alla successiva. È il modo in cui il wayfinding evita il paradosso del piano tradizionale, che pretende di conoscere in anticipo un percorso che per definizione non è conoscibile.

Agnosticismo rispetto al tracker

Wayfinder è stata progettata per funzionare con qualsiasi issue tracker: GitHub, GitLab o semplici file markdown locali. La scelta del tracker è una decisione di workflow del team, non un vincolo della skill. Questo agnosticismo è reso possibile dal fatto che Wayfinder usa solo primitive che ogni tracker possiede: issue (o file), label (o convenzioni di frontmatter), dipendenze (native o dichiarate) e assegnazione (o stato "claimed").

Le differenze pratiche tra i tracker sono minime e riguardano solo la meccanica di rappresentazione. Su GitHub e GitLab, la mappa e i ticket sono issue, le label tipologiche sono etichette native e il blocking usa la relazione di dipendenza tra issue. Su un tracker locale in markdown, la mappa è un file WAYFINDER.md nella root del repo, i ticket sono file separati (es. in .wayfinder/tickets/), e il blocking si rappresenta con una riga esplicita nel frontmatter di ciascun ticket che indica gli id dei ticket bloccanti. In questo caso, la frontier va dedotta leggendo i file aperti e incrociando le dichiarazioni di dipendenza.

Questa flessibilità non è un compromesso: è una scelta deliberata. Wayfinder non vuole imporre un tracker, perché la scelta dello strumento dipende dal contesto del progetto — dimensioni del team, distribuzione geografica, policy aziendali, preferenze di workflow. La skill si adatta allo strumento che il team già usa, invece di richiedere l’adozione di una piattaforma specifica. I concetti fondamentali — mappa, ticket, frontier, blocking, claim — restano identici in ogni implementazione, perché non dipendono dalla tecnologia ma dalla logica del wayfinding.

Best practice e note operative

Nomi leggibili e significativi per i ticket

La regola del naming è una delle più importanti in Wayfinder, e la sua violazione è tra gli errori più comuni nelle prime sessioni di utilizzo. Un ticket non è un record di sistema: è un elemento di conversazione tra esseri umani e agenti. Un nome come "issue #42" non dice nulla a chi apre la mappa; "Decidere il formato di export" dice esattamente quale decisione è in gioco.

La convenzione pratica è: il titolo del ticket deve rispondere alla domanda "cosa stiamo decidendo?". Non "cosa dobbiamo fare" (quello è il compito), ma quale scelta deve essere presa. Esempi di nomi efficaci:

"Decidere il formato di export" — non "Implementare export" (quello è un task, non una decisione)
"Scegliere il sistema di caching" — non "Valutare Redis e Memcached" (la valutazione è il mezzo, la scelta è la decisione)
"Definire lo schema del payload di risposta" — non "Scrivere il payload" (scrivere è l’esecuzione, definire è la decisione)

La distinzione tra nome del ticket e contenuto del ticket è sottile ma cruciale: il nome dichiara la decisione, il contenuto (nel corpo dell’issue) contiene il contesto, le opzioni e l’esito. Questo permette alla mappa di funzionare come indice — una riga per ticket, leggibile a colpo d’occhio — senza dover aprire ogni singolo issue per capire di cosa si tratta.

Un criterio di verifica rapida: se un collega che non ha mai visto il progetto apre la mappa, deve essere in grado di capire l’oggetto di ogni decisione aperta solo leggendo i titoli. Se deve aprire i ticket per orientarsi, il naming non è abbastanza leggibile.

Gestione dell’Out of scope

La sezione "Out of scope" è spesso la più trascurata nelle prime implementazioni, ma è una delle più strategiche. Il suo scopo non è solo documentare ciò che non si farà: è proteggere la mappa dalla deriva. Senza una dichiarazione esplicita di esclusione, c’è il rischio concreto che qualcuno — un membro del team, una sessione agente successiva, uno stakeholder — riscopra un’idea accantonata e la reintroduca, facendo deragliare il lavoro.

La regola pratica per popolare l’Out of scope: ogni volta che durante il grilling o la risoluzione di un ticket emerge un’idea che è chiaramente rilevante ma volutamente esclusa dall’effort attuale, va annotata esplicitamente. Non basta pensarla: va scritta. La scrittura ha due effetti. Il primo è che rende la decisione di esclusione visibile e verificabile — chiunque può contestarla, ma deve farlo esplicitamente, non accidentalmente. Il secondo è che evita il lavoro di riscoperta: se l’idea viene riproposta tre mesi dopo, basta indicare la riga in Out of scope per chiudere la discussione — o per riaprirla consapevolmente, se le condizioni sono cambiate.

Alcuni esempi concreti di voci in Out of scope:

"Localizzazione in altre lingue — fuori scope per la v1, da rivalutare dopo il lancio"
"Supporto per browser legacy — il target è l’ultima versione di Chrome e Firefox"
"Migrazione del database legacy — si usa il nuovo schema, la migrazione è un progetto separato"

La formulazione ha una sua importanza: ogni voce dovrebbe indicare non solo cosa è escluso, ma anche perché e, se possibile, quando potrebbe essere riconsiderato. Questo trasforma l’Out of scope da un elenco di divieti in un registro di decisioni differite, con la motivazione che permette di rivalutarle in futuro.

C’è una relazione stretta tra Out of scope e "Not yet specified". La differenza è: in "Not yet specified" ci sono decisioni che dovranno essere prese (la nebbia le nasconde, ma il percorso le richiederà); in Out of scope ci sono decisioni che non dovranno essere prese in questo effort. Confondere le due sezioni è un errore comune: se una voce finisce in Out of scope quando in realtà è necessaria, il lavoro arriverà a un punto morto senza una via d’uscita dichiarata. La verifica da fare al momento di scrivere una voce è: "se non decidiamo questo, possiamo comunque raggiungere la destination?" Se la risposta è no, la voce non è fuori scope — è solo non ancora specificata.

Riferimenti: repository, autore, documentazione

La skill Wayfinder è distribuita come parte del repository GitHub mattpocock/skills, un progetto che ha raggiunto 160.000 stelle e 7 milioni di download dalla versione 1.1. Il repository è pubblico e clonabile:

git clone https://github.com/mattpocock/skills.git

All’interno del repository, la skill si trova in skills/engineering/wayfinder/SKILL.md, mentre la documentazione estesa è in docs/engineering/wayfinder.md. Il file SKILL.md è il punto di ingresso: contiene la descrizione sintetica, i concetti chiave e le istruzioni operative minime. La documentazione in docs/ approfondisce i casi d’uso, le modalità operative e le best practice.

L’autore è Matt Pocock (aihero.dev), che mantiene il repository e la skill. La scelta di distribuire Wayfinder come skill — e non come framework o libreria — è coerente con la filosofia del progetto: la skill è pensata per essere caricata in un ambiente di sviluppo con capacità agente (tool che supportano l’esecuzione di subagent e comandi come /research, /prototype, /grilling), e non come dipendenza da installare.

Per chi inizia, il percorso consigliato è: clonare il repository, leggere SKILL.md per il quadro generale, poi docs/engineering/wayfinder.md per i dettagli operativi. La documentazione è il riferimento autorevole per le convenzioni di naming, la struttura della mappa e i flussi di lavoro — questo report ne è una sintesi operativa, ma non sostituisce la fonte primaria. Il repository è inoltre un punto di osservazione utile per vedere come la skill evolve: essendo pubblico e molto diffuso, le best practice emergono dall’uso reale e vengono incorporate nelle versioni successive.