wayfinder

name	wayfinder
description	Run when the work is bigger than one session AND the route is unknown: "this will take multiple sessions", "where do we even start", a large migration, a repo-wide audit, "untangle X across the codebase" — any ask where you cannot yet draw the ticket breakdown because the facts that would shape it are missing. Use even if you feel able to sketch a plan now — a plan drawn before scouting encodes guesses as commitments. The unit of progress here is an INVESTIGATION ticket: a time-boxed scouting task whose deliverable is knowledge (a written finding), which then reshapes the map. Slash alias: /wayfinder.
metadata	{"short-description":"Investigation tickets for unmapped multi-session work — scout first, plan from findings"}

Wayfinder (investigation tickets for unmapped multi-session work)

The core inversion

/to-tickets slices work you understand. Wayfinder is for work you do not yet understand: instead of tickets that build, you cut tickets that find out — and each finding redraws the remaining plan. Planning and doing stay separate; the strong pull to "just start the work" mid-investigation is usually the signal you have reached the edge of what is known, not a reason to stop mapping.

Workflow

1. Name the destination first. One or two lines: what does "done" look like — a locked decision, a spec, or an in-place change? The destination fixes scope; everything not on a route toward it is out of scope.
2. Chart the initial map (one session, no more):
   • Run /grill-the-plan breadth-first to surface what is unknown. If nothing genuinely unknown surfaces, you do not need wayfinder — go straight to /to-tickets.
   • Write the map as one document/issue with sections: Destination · Decisions so far (empty at start) · Not yet specified (the fog: in-scope questions not yet sharp enough to ticket) · Out of scope.
   • The map is an index, not a store: each finding lives in its ticket; the map holds one summary line + link per resolved ticket.
3. Cut investigation tickets for every question you can state precisely NOW (the test is "can I state the question?", not "can I answer it?"). Each ticket:
   • Question — one sharp question, answerable within the time box.
   • Time box — a fraction of one session; when it expires, write up what was learned and what blocked the rest. A partial finding is a valid deliverable; an expired silent ticket is not.
   • Deliverable — a written finding: what was examined, what is now known, what it changes about the plan. Knowledge, not code (a throwaway probe is fine but the finding is the artifact).
   • Blocked by — wire dependency edges in a second pass, after all tickets exist and can reference each other. Leave the rest as fog — do not pre-slice questions you cannot yet state.
4. Work the frontier, one ticket per session. Pick an unblocked, unclaimed ticket; claim it before doing anything (in this repo's shared files, that means ledger-append-etiquette rules apply); resolve it; record the finding on the ticket; append the one-line summary to the map's Decisions so far.
5. Let findings reshape the map after every ticket: sharpen fog into new tickets, delete tickets a finding invalidated, move discoveries beyond the destination to Out of scope (they never graduate back). This redrawing IS the method working, not churn.
6. Hand over between sessions. Cross-session state rides on this repo's session-handover chain: end each wayfinder session with a handover doc pointing at the map and naming the next frontier ticket. Wayfinder complements session-handover — the map holds the plan's state, the handover holds the session's state; keep both.
7. Declare the map complete when nothing is left to decide — fog empty, frontier empty. Then, and only then, hand the now-known route to /to-tickets for build slicing (or execute directly if the destination was a decision).

Ticket flavors

• Read — docs/code/logs archaeology; finding = a summary with pointers.
• Probe — a throwaway experiment or measurement; finding = the numbers and what they rule out (for eval-shaped probes, respect rlvr-harness-traps before trusting a surprising number).
• Ask — a decision only the user can make; resolves through live exchange via /grill-the-plan, never by answering it yourself.

Do not

• Do not start building while charting — a wayfinder session either maps or (once mapped) executes exactly one ticket, never both.
• Do not resolve more than one ticket per session; budget discipline is what keeps concurrent sessions from colliding.
• Do not paste findings into the map body — link them; the map stays low-res.
• Do not ticket the fog prematurely; a vague ticket wastes its whole time box sharpening its own question.
• Do not let out-of-scope discoveries back in because they were interesting; record and move on.
• Do not present the map as a guarantee of the route — it is the current best knowledge, and the next finding may redraw it.

Method adapted from mattpocock/skills skills/productivity/wayfinder/SKILL.md (MIT) — see THIRD_PARTY_NOTICES.md.