A big idea just arrived — too big for one agent session, and wrapped in fog: path from here to destination has not appeared. Wayfinding is finding that path, not charging straight at the destination. This skill draws the path into a map on the issue ledger, then works its decision tickets — each ticket is a question whose answer is a decision, not a build slice — one at a time, until the path to the destination is clear and there is nothing left to decide.
This is the prior /proposetier: propose assumes the shape of the work is known; wayfinder is for when it is not known.
WHAT
Purpose and context
- Purpose: find the PATH to the destination for a chunk of work that is too large and still fuzzy — build a map of decision tickets on the issue ledger then solve each ticket until the path is clear and there is nothing left to decide.
- Trigger (when to use): invoke manually when there is a big idea whose shape is not yet clear, BEFORE both
/propose. Manual-only (disable-model-invocation: true). - Non-goals: does not produce deliverables/builds (that is after
/propose); does not answer on behalf of the human side in HITL tickets; does not pre-slice the fog into tickets; does not solve work beyond the destination (out of scope).
Mental model
ý tưởng loose → Destination → bản đồ (issue wayfinder:map, chỉ mục) → ticket quyết định (issue con, cạnh chặn) → frontier → giải một ticket → Decisions-so-far + dọn sương → … → đường rõ → bàn giao /propose.
Plan, don't do
Wayfinder by default is planning: each ticket solves a decision, and the map is done when the path is clear — nothing left to decide before someone goes to do the work. What pulls you to jump in and do is usually a signal that you have reached the edge of the map and it is time to hand off to /propose. Produce decisions, not deliverables.
Name by NAME, not by id
Each map and ticket is an issue, so it has a name — its title. In everything the reader sees (narrative, Decisions-so-far), call it by that name, never by a bare id. A wall of #42, #43, #44 is unreadable; a name reads at once. Ids and links do not disappear — the name wraps the link — but they go inside the name, not instead of the name.
Four ticket types
Each ticket is HITL (a live person answers) or AFK (agent running alone). A HITL ticket is only solved through live exchange; the agent never stands in for the person — a grilling agent that answers its own questions has already broken this.
- research (AFK) — read docs/APIs/knowledge bases to pull out a fact that a decision is waiting on. Solve with a subagent
/research(or/agent-reach). Use when knowledge outside the current directory is needed. - prototype (HITL) — raise the resolution of the discussion with something concrete to react to: an outline, a draft, a stub, or UI/logic. Use when "what does it look like" / "how does it behave" is the main question.
- grilling (HITL) — one-question-at-a-time conversation. The default case.
- task (HITL or AFK) — work that must be DONE by hand before a decision can be made: register a service to evaluate an API, grant permissions, move data to see its shape. The only kind that does instead of decides — and it earns its place because it unlocks a decision, not because it delivers a deliverable.
Fog of war
The map is deliberately incomplete: don't draw what you haven't seen. Beyond the live tickets is fog — a blurred view of decisions you know are coming but can't yet pin down, because they hang on open questions. Solving one ticket clears the fog ahead of it, graduating anything now pinnable into a new ticket — one at a time, until the path to the destination is clear.
Fog or ticket? The test is can the question be stated precisely NOW — not can it be answered yet.
- Ticket when the question is already sharp — even if it's blocked and you can't do it yet.
- Not yet specified when you can't state it sharply yet. Don't pre-cut fog into ticket-sized pieces: it's coarser than a ticket, one patch may graduate into several tickets, or none, when the frontier reaches it.
Out of scope
Fog only gathers toward the destination. The destination fixes the scope, so going beyond it is out of scope — not fog, not Not-yet-specified. It has its own section: work you knowingly exclude from thiseffort. Out-of-scope never graduates. A ticket that already exists but turns out to lie beyond the destination → close it and leave a line in Out-of-scope, don't solve it on the way.
Input and output contract
| Field | Required? | Meaning | |
|---|---|---|---|
| In | loose idea | yes (Chart mode) | the thing to find a path for |
| In | map (issue wayfinder:map) |
yes (Work mode) | the map already built |
| In | specific ticket | no (Work mode) | none → take the first frontier ticket |
| Out | map issue + child issues + blocking edges | Chart | Destination, Not-yet-specified sketch, Decisions-so-far empty |
| Out | a claimed ticket → resolved → closed + a pointer in Decisions-so-far | Work | along with newly surfaced tickets / graduated fog / out-of-scope updates |
Rules and capabilities
- RULE-01 (MUST): Manual-invoke-only (
disable-model-invocation: true) — wayfinder is a deliberate action by the user, not something the model jumps into on its own. See[[skill-craft]]. - RULE-02 (MUST): Plan, don't do — generate decisions, not deliverables. Wanting to jump in and do = reaching the edge of the map = hand off
/propose. - RULE-03 (MUST): One ticket per session (except research), and claim before working (using
frontier.py+ theclaimcell of the ledger). - RULE-04 (MUST): The ledger is the source of truth; the remote tracker is a mirror. Read
[[issue-tracker]]for how this is expressed in this repo. - Capabilities: read/write issues on the ledger (create, link blocking edges, claim, close); query the frontier; live conversation with the user for HITL tickets; dispatch research subagents in parallel.
Failure boundaries
- Drawing the frontier surfaces no fog → the path is already clear, no map needed: stop, ask the user how they want to proceed.
- HITL ticket has no one to answer → blocked; the agent does not answer on their behalf.
- Ticket already claimed by another session → do not resolve; pick another frontier ticket.
- A solution reveals work that lies beyond the destination → close the ticket, record Out-of-scope (cancelled for that ticket).
- The pull to jump in and do → reaching the edge of the map → hand off
/propose.
HOW
Main workflow
| Step | Type | Inputs | Action | Outputs/exit | Failure/next |
|---|---|---|---|---|---|
| W01 | judgment | idea | (Chart) Name the destination via /grilling + /domain-modeling |
a one-sentence Destination | — |
| W02 | judgment | Destination | (Chart) Draw the frontier breadth-first | decide to open + first step | no fog → stop, ask user |
| W03 | effect | W01–W02 | (Chart) Create a mappable map + pinned tickets, connect blocking edges on the second pass | issue map + sub-issues | — |
| W04 | effect | research ticket | (Chart) Fire research subagents in parallel, then stop | findings attached to context pointers | — |
| W05 | deterministic | map | (Work) Load the map, select a ticket (user-specified or frontier.py --map <id>), claim first |
claimed ticket | already claimed → choose another |
| W06 | judgment | ticket | (Work) Solve — zoom when needed; for HITL, ask a live person | solution | stuck → /grilling + /domain-modeling |
| W07 | effect | solution | (Work) Record resolution, close issue (status: done), append Decisions-so-far; create new ticket / graduate fog / mark out-of-scope |
updated map | — |
Step-by-step details (source of truth for W01–W07):
Two modes. Both: never solve more than one ticket per session — except research.
Chart the map
User invokes with a loose idea.
- Name the destination. Run
/grilling+/domain-modeling(if any) to pin this destination down to find a path to something. The fixed destination defines the scope, so lock it first. → Done when: a single Destination sentence that every later session can orient around. - Draw the frontier. Grill again, breadth-first: fan out across the space instead of deep along one thread, pull out the open decisions and the first steps that can be done right away. No fog pulled out → the path is already clear, no map needed; stop, ask the user how they want to proceed.
- Create the map (label
wayfinder:map): Destination + Notes filled in, Decisions-so-far empty, fog sketched into Not-yet-specified. - Create the mappable tickets as sub-issues — then connect the blocking edges on the second pass (issues need ids before they can point at each other). → Done when: every mappable ticket exists, the unmappable parts stay as fog.
- Fire research subagents. Each ticket
research→ one subagent solves in parallel, records findings, attaches context pointers from the ticket. - Stop — charting the map is the job of one session; it does not self-solve any ticket.
Work through the map
User invokes with a map. Tickets are optional — if absent, you choose the next decision, not the user.
- Load the map (low-resolution view, not every ticket body).
- Choose a ticket. If the user names one, use it. Otherwise take the first frontier ticket (
frontier.py --map <id>). Claim it — write the cellclaim, before everything. - Solve — zoom when needed: fetch the full body of the relevant ticket on demand; call the named Notes skills only. If stuck,
/grilling+/domain-modeling. - Record the solution: post the solution as resolution, close the issue (
status: done), append a pointer to the Decisions-so-far of the map. - Add newly revealed tickets (create-then-wire); graduate froth that the solution just pinned, clear it from Not-yet-specified. If the solution reveals a ticket beyond the destination → mark out of scope. If the solution negates another part of the map → update/delete that ticket.
Branches
| ID | Kind | Guard | Behavior | Skip / failure | Rejoin |
|---|---|---|---|---|---|
| B01 | user_optional | user invokes with an existing map | Work through the map mode (W05–W07) instead of Chart (W01–W04) | — | end the session after one ticket |
| B02 | conditional_required | research-type ticket | solve with a subagent /research (or /agent-reach), multiple tickets may be run in parallel |
— | W07 |
| B03 | conditional_required | HITL ticket (prototype/grilling/task-HITL) | solve only via live exchange with a person | no person → blocked | W07 |
| B04 | recovery | solution negates another part of the map | update/delete that ticket | — | W07 |
Validation and stopping
Chart stops after W04 (it does not solve any ticket itself). Work stops after exactly one ticket (except research). The map is done when the path to the destination is clear and there is nothing left to decide → hand off /propose. The next ticket is decided by frontier.py + the cell claim , not guessed.
Examples
- Positive: "/wayfinder chuyển overstack sang multi-model dispatch" → grill out a one-line Destination, the frontier reveals 3 tickets (1 research on the provider API, 2 grilling) → create map
wayfinder:map+ 3 child issues, wire the second-pass blocking edges, fire 1 research subagent → stop. - Boundary/failure: "/wayfinder " but the frontier ticket is grilling (HITL) and the user is absent → blocked, the agent does not answer its own question; it does not resolve the second ticket in the session.
Reference — Map
The map is an issue on the ledger (label wayfinder:map). Its ticket is a child issue. The map is an index, not a store: it lists the decisions made and points to the ticket holding the detail — a decision lives in exactly one place (its ticket), the map does not retell it, only gist and link. Where the map, child tickets, blocking edges, and frontier query live is tracker-dependent — read [[issue-tracker]] § "Wayfinding operations".
Map body (loaded once per session):
## Destination
<đi tới cuối bản đồ này trông như thế nào — spec, quyết định, hay thay đổi mà nỗ lực này tìm đường tới. Một hai dòng; mỗi phiên định hướng vào nó trước khi chọn ticket.>
## Decisions so far
<!-- chỉ mục — một dòng mỗi ticket đã đóng: đủ để phán đoán liên quan, rồi zoom link lấy chi tiết -->
- [<tên ticket đã đóng>](link) — <gist một dòng của lời giải>
## Not yet specified
<!-- fog of war: sương trong-phạm-vi chưa ticket được; tốt nghiệp khi frontier tiến tới -->
## Out of scope
<!-- việc bị loại khỏi ĐÍCH này; đóng, không bao giờ tốt nghiệp -->
The ticket is a child issue, the body is the question, medium-sized for one session:
## Question
<quyết định hay điều tra mà ticket này giải>
Origin
- Distilled from
mattpocock/skills—skills/engineering/wayfinder/SKILL.md(clonescratchpad/mattpocock-skills/, 2026-07-15). - Absorb via
/propose→150726-mattpocock-absorb(T8), taskT-260715-01. Stands on the T6/T7 ledger infrastructure. - Commit: (verify-before-commit fills in)