A loose idea appears: it is too large for a single agent session to contain, and it is surrounded by fog; from here to destination the path is not yet visible. The goal of Wayfinding is to find this path, not to charge headlong at the destination. This skill charts the path as shared mapon the repo issue tracker, then processes decision ticketsone by one (they carry problems that require decisions to resolve, not build slices to execute), until the route is clear.
Different efforts have different destinations, and naming it is the first action of charting; it shapes every ticket. It might be a spec to hand off and iterate on, a decision that must be settled before planning, or a change completed in place such as a data-structure migration. The map is domain-agnostic: engineering work, course content, or anything matching this shape will do.
Plan only, do not act
Wayfinder is by default used for planning: each ticket resolves one decision; the map is only complete when there is nothing left to decide before someone acts and the path is fully clear. The urge to just do the work usually means you have reached the edge of the map and it is time to hand off. An effort can override this default in Notes to include execution in the map; otherwise it produces only decisions, not deliverables.
Refer by name
Every map and every ticket is an issue, so each has a name: its title. In all human-facing content, including narratives and the map's Decisions-so-far, refer to it by name, not just a bare id, number, or slug. A wall of #42, #43, #44 is hard to read; a name is understandable at a glance. Ids and URLs do not disappear; they are wrapped inside the name's link, but they do not replace the name on their own.
Shared map
The map is a separate issue on this repo issue tracker with a wayfinder:map label, and is the canonical artifact. Its tickets are the map's child issues.
The map is index, not a store. It lists the decisions already made and points to the tickets that hold the details; a decision exists in only one place, its ticket. Therefore the map does not restate details, only gives the gist and a link.
The physical expression of the map, child tickets, blocking, and frontier queries depends on the tracker. The issue tracker should already be provided; if not, have the user run /setup-matt-pocock-skills. Consult the "Wayfinding operations" section of the tracker doc to learn how this repo expresses them. If there is no tracker, use the local-markdown tracker by default.
Map body
The map is a low-resolution global view, loaded once per session. Open tickets are not listed in it; they are open child issues, found via query.
## Destination
<what reaching the end of this map looks like: the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
## Notes
<domain; skills every session should consult; standing preferences for this effort>
## Decisions so far
<!-- the index: one line per closed ticket, enough to judge relevance, then zoom the link for the detail the ticket holds -->
- [<closed ticket title>](link): <one-line gist of the answer>
## Not yet specified
<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
## Out of scope
<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
Tickets
Every ticket is the map's child issue; the tracker's issue id is its identity. The body is a question, sized to fit within a 100K token agent session:
## Question
<the decision or investigation this ticket resolves>
Every ticket carries a wayfinder:<type> label, with value research、prototype、grilling、task(see Ticket Types)。
Session claim ticket, is, before any work begins,firstassign the ticket to the dev driving the map, so concurrent sessions skip it. This assignee is the claim: an open and unassigned ticket is unclaimed.
Blocking uses the tracker's native dependency relationship; this matters because the tracker UI visualizes the frontier, so humans can see which tickets are available without opening the map. Only fall back to the body convention when the tracker has no native blocking. A ticket is unblocked;frontier are open, unblocked, unclaimed children, i.e. the edge of the known world.
The answer is not written into the body, but recorded at resolution time (see Work through the map). Assets produced when resolving a ticket are linked out from the issue, not pasted into the body.
Ticket types
Every ticket is either HITL(human in the loop, handled together with a human who can speak for themselves) or AFK(agent-driven independently). HITL tickets can only be resolved through live exchange; an agent must never answer on the human's behalf. Once a grilling agent asks and answers its own questions, it is already broken.
- Research(AFK): read local resources such as documentation, third-party APIs, or knowledge bases to find the facts that a decision is waiting on. Hand it to a
researchresolved by a subagent that calls the Skill tool and specifies research. Use when knowledge outside the current working directory is needed. subagent research - Prototype(HITL): raise discussion fidelity through a cheap, rough, concrete artifact, such as an outline, rough take, stub, or by calling the Skill tool and specifying
prototypeto write UI/logic code. Prototypes are linked as assets. Use when the core question is "how should it look" or "how should it behave". - Grilling(HITL): Conversation. The default type. Always call the Skill tool twice, specifying
grillinganddomain-modeling。 - Task(HITL or AFK): manual work that must be done before making decision but that itself has nothing to decide, prototype, or research. For example, registering for a service to evaluate its API, configuring access permissions, moving data to see its shape. This is the only type that do instead of decides; it exists by unlocking decisions, not by delivering a destination. Use AFK when an agent can complete it independently; otherwise give the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and the facts that follow-up tickets depend on (credentials location, new URLs, row counts, etc.).
Fog of war
The map is intentionally incomplete: do not depict what you cannot yet see. Beyond the tickets is fog: the decisions and investigations you can sense will come later, but they hang above still-unresolved questions and cannot yet be pinned down. Resolving a ticket clears a patch of fog in front of it, upgrading questions that can now be stated into new tickets; one at a time, until the path to the destination is clear and no tickets remain.
The map's Not yet specified section is used to record this hazy vision: suspected problems, areas to revisit later. This is the unexplored frontier leading to the destination; everything is in scope, it is just not clear enough yet to become a ticket. You can write it as coarsely as your vision allows; it is also a signpost for collaborators reading where this effort is heading.
Fog or ticket? The test criterion is whether you can state the problem clearly now, not whether you can answer it now.
- Ticket when The problem is already clear, even if it is blocked and cannot be handled right now.
- Not yet specified when You can't state it that clearly yet. Don't pre-cut fog into ticket-sized pieces: fog is coarser than tickets; once the frontier arrives, a patch of fog may graduate into multiple tickets, or none at all.
Not yet specified Exclude what has already been decided (Decisions so far), what is already a live ticket, and what is out of scope (next section).
Out of scope
Fog only gathers in the direction of the destination. The destination fixes scope, so work beyond it is out of scope, not fog, and does not belong to Not yet specified. It goes into the map's separate Out of scope section: work you are deliberately excluding from this effort. What puts it here is scope, not sharpness.
Out-of-scope work never graduates; the frontier stops at the destination. It only comes back if the destination is redrawn, and then it should become a new effort, not a resumption.
Excluding something from scope is a scoping act, not a step on the route. If an existing ticket is found to lie outside the destination (mis-scoped during charting, or exposed by some resolution), it should be close it(a closed ticket is explicitly not on the frontier), and leave a line in the Out of scope section: the gist plus why it is out of scope, and a link to the closed ticket. Don't put it in Decisions so far; the latter only records the route actually traveled, and a scope boundary is not a step on the route.
Invoke
two modes. Either way,never resolve more than one ticket per session, except for research tickets.
Charting the map
The user invokes it with a loose idea.
- Name the destination. Invoke the Skill tool twice, specifying
grillinganddomain-modeling, to determine the spec, decision, or change the map is meant to find. The destination fixes scope, so settle it first. - Map the frontier. Then grill once more, this time using breadth-first: cover the whole space rather than going deep into one thread, surfacing open decisions and first steps that can be started now.If there is no fog, the path is already clear and the whole journey can be completed in one session; you don't need a map. Stop and ask the user how to proceed.
- Create the map(label
wayfinder:map): fill in Destination and Notes, leave Decisions-so-far empty, sketch the fog into Not yet specified。 - Create the tickets you can specify now as the map's child issues, then wire the blocking edges on a second pass (issues need ids before they can reference each other). Wiring splits them into frontier and blocked; anything still unclear stays in Not yet specified。
- Launch research subagents. For each
researchticket just created, launch in parallel a subagent that invokes the Skill tool and specifiesresearchto resolve it; findings are kept on a throwawayresearch/<name>branch, and a context pointer is left from the ticket. - Stop. Charting is one session's work; do not manually resolve tickets in this session.
Advancing along the map
The user invokes it with a map (URL or number). The ticket is optional; when there is no ticket, you choose the next decision, not the user.
- Load map: a low-resolution view, not every ticket body.
- Choose a ticket. If the user names one, use it; otherwise take the first frontier ticket in order.Claim it: Before any work begins, assign it to yourself first.
- Resolve it: as needed zoom, only fetch the full body of related or closed tickets when needed; call the
## Notesskills mentioned in the block. When unsure, call the Skill tool twice, specifyinggrillinganddomain-modeling。 - Record the resolution: publish the answer as a resolution comment ,close issue, and append a context pointer to the map's Decisions-so-far.
- Add newly emerged tickets (create-then-wire); graduate fog that the answer has already clarified into tickets, and from Not yet specified clear out each upgraded patch so it exists only as a new ticket. If the answer indicates that this or another ticket lies outside the destination, rule out of scopeit, rather than resolving it as part of the route. If this decision invalidates other parts of the map, update or delete those tickets.
The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker at the same time.