skills/.changeset/wayfinder.md

mattpocock-skills

mattpocock-skills
minor

Graduate and reframe wayfinder — the skill for planning a huge chunk of work, more than one agent session can hold. It moves out of in-progress/ into engineering/ (plugin entry, top-level + Engineering READMEs under User-invoked, a docs page at docs/engineering/wayfinder.md, and a route in ask-matt), landing as a mature skill. The rename and reframe that got it there:

• decision-mapping is renamed to wayfinder, invoked as /wayfinder. "Decision map" was jargony and inaccurate — only one ticket type is actually a decision. The reframe charts a route through a foggy problem instead, giving one coherent leading-word frame — fog of war, frontier, the map — rather than an invented term layered on top.
• Destination as the leading word. Wayfinding finds the way to a destination; it doesn't charge at building it. Naming the destination is the first act of charting — it fixes the scope and shapes every ticket — so the map gains a ## Destination field every session orients to, and triage pins it before any ticket exists.
• Plan, don't do. The map produces decisions, not deliverables; it's done when nothing is left to decide before someone builds the thing. An effort can override this in its Notes.
• The map is an index, not a store. A decision lives in exactly one place — its ticket — so the map only gists and links, never restates; graduating fog into a ticket clears the graduated patch so nothing lingers in two places.
• Collaborative by default. The map moves off a local Markdown file onto the repo's issue tracker: a single wayfinder:map issue whose tickets are its child issues — one shared URL the team can watch. Sessions load the map at low resolution and zoom into tickets on demand. Wayfinder stays tracker-agnostic (GitHub, GitLab, local-markdown) behind a pointer in docs/agents/issue-tracker.md, and setup-matt-pocock-skills seeds the "Wayfinding operations" section.
• Claim by assignment, not a label. A session claims a ticket by assigning it to the driving dev — the assignee is the claim — freeing the label vocabulary to wayfinder:<type> alone.
• Native blocking. Blocking prefers the tracker's native dependency relationship, which renders the frontier visually in the tracker's own UI so the human sees what's takeable without opening the map. GitHub and GitLab templates spell out the native recipe, with a body-convention fallback.
• Fog vs. out of scope, split. Two plainly-named map sections — ## Not yet specified (in-scope fog that graduates as the frontier advances) and ## Out of scope (work ruled beyond the destination, closed, never graduating) — so beyond-destination work no longer reads as takeable frontier.
• A fourth task ticket type. For literal manual work that blocks a decision (provisioning access, moving data, signing up for a service) — the one type that does rather than decides, earning its place by unblocking a decision.
• HITL / AFK ticket classification. Every ticket type is HITL (human in the loop — grilling, prototype) or AFK (agent alone — research; task is either). A HITL ticket only resolves through the live exchange, so "wait for the human" falls out of the label — a grilling agent that answers its own questions has, by definition, broken HITL. (This fixes students' reports of /wayfinder grilling itself instead of the human.)
• No-fog early exit restored. If the opening breadth-first grilling surfaces no fog, the journey is small enough for one session — so it stops and asks how you'd like to proceed rather than building a map nobody needs.