mattpocock/wayfinder

Eine vage Idee ist angekommen, zu groß für eine einzige Agentensitzung und in Nebel gehüllt: Der Weg von hier zum Ziel ist noch nicht sichtbar. Wayfinding bedeutet, diesen Weg zu finden, nicht auf das Ziel zuzustürmen. Dieser Skill kartiert den Weg als gemeinsame Karte im Issue-Tracker des Repos und arbeitet dann seine Entscheidungs-Tickets ab (Fragen, deren Auflösung eine Entscheidung ist, keine Scheiben eines auszuführenden Builds), eines nach dem anderen, bis die Route klar ist.

Das Ziel variiert pro Vorhaben, und es zu benennen ist der erste Akt des Kartierens: Es formt jedes Ticket. Es kann eine Spezifikation sein, die übergeben und iteriert wird, eine Entscheidung, die vor Planungsbeginn festgezurrt wird, oder eine Änderung, die direkt vor Ort vorgenommen wird, wie eine Datenstruktur-Migration. Die Karte ist domänenunabhängig: Ingenieursarbeit, Kursinhalte, alles, was in diese Form passt.

Plane, handle nicht

Wayfinder ist standardmäßig planend: Jedes Ticket löst eine Entscheidung, und die Karte ist fertig, wenn der Weg klar ist und nichts mehr zu entscheiden bleibt, bevor jemand losgeht und die Sache umsetzt. Der Drang, die Arbeit einfach zu erledigen, ist normalerweise das Signal, dass du den Rand der Karte erreicht hast und es Zeit für die Übergabe ist. Ein Vorhaben kann dies in seinen Notizen überschreiben und die Ausführung in die Karte selbst tragen. Fehlt dies jedoch, produziere Entscheidungen, keine Ergebnisse.

Nach Namen verweisen

Jede Karte und jedes Ticket ist ein Issue, also hat es einen Namen: seinen Titel. In allem, was der Mensch liest (Erzählung, die bisherigen Entscheidungen der Karte), beziehe dich auf diesen Namen, niemals auf eine bloße ID, Nummer oder einen Slug. Eine Wand aus #42, #43, #44 ist unlesbar; Namen sind auf einen Blick erfassbar. Die ID und URL verschwinden nicht; ein Name umschließt seinen Link, aber sie reiten innerhalb des Namens, ersetzen ihn nie.

Die Karte

Die Karte ist ein einzelnes Issue im Issue-Tracker dieses Repos, gekennzeichnet mit wayfinder:map, das kanonische Artefakt. Ihre Tickets sind Unter-Issues der Karte.

Die Karte ist ein Index, kein Speicher. Sie listet die getroffenen Entscheidungen auf und verweist auf die Tickets, die die Details enthalten; eine Entscheidung lebt an genau einem Ort, ihrem Ticket, daher wiederholt die Karte sie nie, sondern fasst sie nur kurz zusammen und verlinkt sie.

Wo die Karte, ihre Unter-Tickets, Blockierungen und die Grenzflächen-Abfragen physisch leben, ist tracker-spezifisch. Der Issue-Tracker sollte dir mitgeteilt worden sein. Falls nicht, sage dem Benutzer, er solle /setup-matt-pocock-skills ausführen. Konsultiere im Tracker-Dokument den Abschnitt "Wayfinding-Operationen", um zu erfahren, wie dieses Repo sie ausdrückt. Wenn kein Tracker bereitgestellt wurde, verwende standardmäßig den lokalen Markdown-Tracker.

Der Kartenkörper

Die gesamte Karte in niedriger Auflösung, einmal pro Sitzung geladen. Offene Tickets werden nicht aufgelistet: Sie sind offene Unter-Issues, die durch Abfragen gefunden werden.

## Ziel

<wie das Erreichen des Kartenendes aussieht: die Spezifikation, Entscheidung oder Änderung, zu der dieses Vorhaben seinen Weg findet. Ein oder zwei Zeilen; jede Sitzung orientiert sich daran, bevor sie ein Ticket auswählt.>

## Notizen

<Domäne; Fähigkeiten, die jede Sitzung konsultieren sollte; stehende Präferenzen für dieses Vorhaben>

## Bisherige Entscheidungen

<!-- der Index: eine Zeile pro geschlossenem Ticket, genug, um die Relevanz zu beurteilen, dann den Link für das Detail zoomen, das das Ticket enthält -->

- [<Titel des geschlossenen Tickets>](link): <einzeilige Zusammenfassung der Antwort>

## Noch nicht spezifiziert

<!-- siehe "Nebel des Krieges": im Umfang befindlicher Nebel, den du noch nicht ticketieren kannst; rückt mit dem Fortschreiten der Grenze nach -->

## Nicht im Umfang

<!-- siehe "Nicht im Umfang": Arbeit, die als jenseits des Ziels ausgeschlossen wurde; geschlossen, rückt nie nach -->

Tickets

Jedes Ticket ist ein Unter-Issue der Karte; die Issue-ID des Trackers ist seine Identität. Sein Körper ist die Frage, zugeschnitten auf eine 100K-Token-Agentensitzung:

## Frage

<die Entscheidung oder Untersuchung, die dieses Ticket klärt>

Jedes Ticket trägt ein wayfinder:<typ>-Label, einer von research, prototype, grilling, task (siehe Ticket-Typen).

Eine Sitzung beansprucht ein Ticket, indem sie es dem Entwickler zuweist, der die Karte vorantreibt, zuerst, vor jeder Arbeit, damit parallele Sitzungen es überspringen. Diese Zuweisung ist der Anspruch: Ein offenes, nicht zugewiesenes Ticket ist nicht beansprucht.

Blockierungen verwenden die native Abhängigkeitsbeziehung des Trackers: Wesentlich, weil sie die Grenze visuell in der eigenen Benutzeroberfläche des Trackers darstellt, damit der Mensch sieht, was übernehmbar ist, ohne die Karte zu öffnen. Nur ein Tracker, dem native Blockierungen fehlen, greift auf eine Körper-Konvention zurück. Ein Ticket ist unblockiert, wenn jedes Ticket, das es blockiert, geschlossen ist; die Grenzfläche (Frontier) sind die offenen, unblockierten, nicht beanspruchten Kinder, der Rand des Bekannten.

Die Antwort ist nicht Teil des Körpers; sie wird bei der Auflösung festgehalten (siehe Arbeite dich durch die Karte). Während der Auflösung eines Tickets erstellte Anhänge werden vom Issue aus verlinkt, nicht eingefügt.

Ticket-Typen

Jedes Ticket ist entweder HITL (Human in the Loop, bearbeitet mit einem Menschen, der für sich selbst spricht) oder AFK, allein vom Agenten gesteuert. Ein HITL-Ticket wird nur durch diesen Live-Austausch gelöst; der Agent ersetzt niemals die Seite des Menschen (ein Grilling-Agent, der seine eigenen Fragen beantwortet, hätte dies gebrochen).

• Research (AFK): Lesen von Dokumentation, Drittanbieter-APIs oder lokalen Ressourcen wie Wissensdatenbanken, um eine Tatsache zu ermitteln, auf die eine Entscheidung wartet. Wird von einem Unteragenten gelöst, der das Skill-Tool mit "research" aufruft. Verwende es, wenn Wissen außerhalb des aktuellen Arbeitsverzeichnisses erforderlich ist.
• Prototype (HITL): Erhöhe die Detailtiefe der Diskussion, indem du ein billiges, grobes, konkretes Artefakt erstellst, auf das reagiert werden kann (eine Gliederung, ein erster Entwurf, ein Stub oder UI-/Logikcode), indem du das Skill-Tool mit "prototype" aufrufst. Verlinkt den Prototypen als Anhang. Verwende es, wenn die Frage ist: "Wie soll es aussehen?" oder "Wie soll es sich verhalten?".
• Grilling (HITL): Gespräch. Der Standardfall. Rufe das Skill-Tool immer zweimal auf, für "grilling" und "domain-modeling".
• Task (HITL oder AFK): Manuelle Arbeit, die erledigt sein muss, bevor eine Entscheidung getroffen werden kann: Nichts zu entscheiden, zu prototypisieren oder zu recherchieren, aber die Diskussion ist blockiert, bis es erledigt ist. Dienst anmelden, damit seine API beurteilt werden kann, Berechtigungen bereitstellen, Daten verschieben, damit ihre Form sichtbar wird. Dies ist der einzige Typ, der tut statt entscheidet, und er verdient seinen Platz, indem er eine Entscheidung entblockt, nicht indem er das Ziel liefert. Der Agent erledigt es allein, wo er kann (AFK); andernfalls übergibt er dem Menschen eine präzise Checkliste (HITL). Wird gelöst, wenn die Arbeit erledigt ist; die Antwort hält fest, was getan wurde und alle daraus resultierenden Fakten (Credentials-Standort, neue URLs, Zeilenanzahlen), von denen spätere Tickets abhängen.

Nebel des Krieges

Die Karte ist bewusst unvollständig: Kartiere nicht, was du noch nicht sehen kannst. Jenseits der Live-Tickets liegt der Nebel des Krieges: die schwache Sicht auf Entscheidungen und Untersuchungen, von denen du spürst, dass sie kommen, die du aber noch nicht festlegen kannst, weil sie von noch offenen Fragen abhängen. Das Auflösen eines Tickets klärt den Nebel vor ihm, lässt das, was jetzt spezifizierbar ist, nach und nach in frische Tickets übergehen, eines nach dem anderen, bis der Weg zum Ziel klar ist und keine Tickets mehr übrig sind.

Der Abschnitt Noch nicht spezifiziert der Karte ist der Ort, an dem diese schwache Sicht festgehalten wird: die vermutete Frage, der Bereich, der später erneut aufgesucht werden muss. Es ist die unentdeckte Grenze in Richtung des Ziels: Alles hier ist im Umfang, nur nicht scharf genug für ein Ticket. Schreibe so lose oder so ausführlich, wie es die Sicht erlaubt; es dient auch als Wegweiser für Mitarbeiter, die lesen, wohin das Vorhaben führt.

Nebel oder Ticket? Der Test ist, ob du die Frage jetzt präzise formulieren kannst, nicht ob du sie jetzt beantworten kannst.

• Ticket, wenn die Frage bereits scharf ist, selbst wenn sie blockiert ist und du noch nicht darauf reagieren kannst.
• Noch nicht spezifiziert, wenn du sie noch nicht so scharf formulieren kannst. Zerlege den Nebel nicht vorab in ticketgroße Stücke: Er ist gröber als ein Ticket, und ein Fleck kann in mehrere Tickets übergehen oder in keines, sobald die Grenze ihn erreicht.

Noch nicht spezifiziert schließt aus, was bereits entschieden ist (Bisherige Entscheidungen), was bereits ein Live-Ticket ist und was nicht im Umfang liegt (nächster Abschnitt).

Nicht im Umfang

Nebel sammelt sich niemals an weg vom Ziel. Das Ziel legt den Umfang fest, daher ist Arbeit jenseits davon nicht im Umfang: Es ist kein Nebel und gehört nicht in Noch nicht spezifiziert. Es bekommt seinen eigenen Abschnitt Nicht im Umfang auf der Karte: Arbeit, die du bewusst aus diesem Vorhaben ausgeschlossen hast. Der Umfang, nicht die Schärfe, bringt sie hierhin.

Nicht im Umfang befindliche Arbeit geht niemals über (die Grenze stoppt am Ziel), sie kehrt nur zurück, wenn das Ziel neu gezeichnet wird, und dann als frisches Vorhaben, nicht als Wiederaufnahme.

Etwas als nicht im Umfang auszuschließen ist ein Umfangsakt, kein Schritt auf der Route. Wenn ein bereits existierendes Ticket sich als jenseits des Ziels herausstellt (während des Kartierens falsch eingeordnet oder durch eine Auflösung aufgedeckt), schließe es (ein geschlossenes Ticket ist eindeutig nicht an der Grenze) und hinterlasse eine Zeile im Abschnitt Nicht im Umfang: die Zusammenfassung plus warum es nicht im Umfang ist, mit Link zum geschlossenen Ticket. Es bleibt außerhalb von Bisherige Entscheidungen, das die tatsächlich begangene Route aufzeichnet; eine Umfangsgrenze ist kein Schritt darauf.

Aufruf

Zwei Modi. Auf jeden Fall: Löse niemals mehr als ein Ticket pro Sitzung, mit Ausnahme von Research-Tickets.

Kartiere die Karte

Der Benutzer ruft mit einer vagen Idee auf.

1. Benenne das Ziel. Rufe das Skill-Tool zweimal auf, für "grilling" und "domain-modeling", um festzulegen, wohin diese Karte ihren Weg findet: die Spezifikation, Entscheidung oder Änderung. Das Ziel legt den Umfang fest, also wird es zuerst geklärt.
2. Kartiere die Grenze. Grille erneut, diesmal breitensuchend: Fächere über den gesamten Raum aus, anstatt tief in einen einzelnen Thread einzutauchen, und bringe die offenen Entscheidungen und die ersten jetzt übernehmbaren Schritte an die Oberfläche. Wenn dies keinen Nebel zutage fördert (der Weg zum Ziel ist bereits klar, die gesamte Reise klein genug für eine Sitzung), brauchst du keine Karte. Stoppe und frage den Benutzer, wie er fortfahren möchte.
3. Erstelle die Karte (Label wayfinder:map): Ziel und Notizen ausgefüllt, Bisherige Entscheidungen leer, der Nebel in Noch nicht spezifiziert skizziert.
4. Erstelle die Tickets, die du jetzt spezifizieren kannst als Unter-Issues der Karte, und verdrahte dann die Blockierungskanten in einem zweiten Durchlauf (Issues brauchen IDs, bevor sie aufeinander verweisen können). Das Verdrahten sortiert sie in die Grenzfläche und die Blockierten; alles, was du noch nicht spezifizieren kannst, bleibt im Nebel: dem Abschnitt Noch nicht spezifiziert.
5. Starte die Research-Unteragenten. Für jedes soeben erstellte research-Ticket starte einen Unteragenten, der das Skill-Tool mit "research" aufruft, um es parallel zu lösen und seine Ergebnisse auf einem Wegwerf-Zweig research/<name> mit einem Kontextzeiger vom Ticket zu erfassen.
6. Stoppe: Das Kartieren ist die Arbeit einer Sitzung; es löst nichts selbst.

Arbeite dich durch die Karte

Der Benutzer ruft mit einer Karte auf (URL oder Nummer). Ein Ticket ist optional: Ohne eines wählst du die nächste Entscheidung, nicht der Benutzer.

1. Lade die Karte: die Ansicht in niedriger Auflösung, nicht jeden Ticket-Körper.
2. Wähle das Ticket. Wenn der Benutzer eines genannt hat, verwende es. Andernfalls nimm das erste Ticket an der Grenzfläche in der Reihenfolge. Beanspruche es: Weise es dir selbst zu, bevor du irgendeine Arbeit beginnst.
3. Löse es. Zoome nach Bedarf: Rufe den vollständigen Körper jedes verwandten oder geschlossenen Tickets auf Abruf ab; rufe das Skill-Tool für diejenigen Fähigkeiten auf, die der Block ## Notizen nennt. Im Zweifelsfall rufe das Skill-Tool zweimal auf, für "grilling" und "domain-modeling".
4. Halte die Auflösung fest: Poste die Antwort als Auflösungskommentar, schließe das Issue und hänge einen Kontextzeiger an die bisherigen Entscheidungen der Karte an.
5. Füge neu aufgetauchte Tickets hinzu (erstellen-dann-verdrahten); lasse jeden Nebel, den die Antwort spezifizierbar gemacht hat, graduieren, und entferne jedes graduierte Stück aus Noch nicht spezifiziert, damit es nur noch als sein neues Ticket lebt. Wenn die Antwort enthüllt, dass ein Ticket (dieses oder ein anderes) jenseits des Ziels liegt, schließe es als nicht im Umfang aus, anstatt es auf der Route zu lösen. Wenn die Entscheidung andere Teile der Karte ungültig macht, aktualisiere oder lösche diese Tickets.

Der Benutzer kann unblockierte Tickets parallel ausführen, erwarte also, dass andere Sitzungen gleichzeitig den Tracker bearbeiten.