wayfind

Pre-computed context

Current user: !gh api user --jq '.login' 2>/dev/null || echo "unknown" Open maps: !gh issue list --label work-map --state open --json number,title --jq '.[] | "#\(.number) \(.title)"' 2>/dev/null || echo "none"

Variables

Arguments: $ARGUMENTS

Purpose

Some efforts are too big to hold at once AND too foggy to ticket — you can't yet phrase half the questions, let alone answer them. /interview needs a coherent task; /planning:plan needs a coherent plan; both presuppose you already know what you're deciding. /wayfind sits upstream of all of them: it turns a too-big-foggy effort into a shared decision map on the work-item tracker, then works that map's frontier one decision at a time until the fog burns off and a real destination (Brief / PRD / PLAN) can be handed onward.

Plan, don't do. A map holds decisions, not build work. Each decision item, once resolved, either sharpens the map or graduates to the destination. The moment the destination is coherent, the map closes and the normal pipeline (/interview → /design → /planning:plan → /implement) takes over. Fog-of-war framing adapted from Matt Pocock's wayfinder — this skill diverges by persisting the map as native tracker primitives, routing each decision to a first-party skill, and keeping execution artifacts in <memory_dir>/<slug>/ (default .work/) — the topic-docs convention's memory tier, slug spec and all (see ${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md) — rather than the map.

Two modes. chart builds or extends a map (interactive only). work picks one item off the map's frontier and drives it to resolution. The default action auto-detects: an existing open map for the topic → work; nothing yet → chart.

The fog test (the one call that governs everything)

For every uncertainty, ask: can I phrase it as a sharp question?

• Sharp (you can state the question, even if you can't answer it yet, even if it's blocked) → it's a decision item on the map (a typed sub-issue).
• Foggy (you can't yet put words to what's uncertain) → it stays prose in the map's Not-yet-specified section. It graduates to a typed item only once working the map has made it sharp enough to phrase.

Sharpness, not blockedness, is the line. A blocked-but-phrasable question is a ticket; an unblocked-but-unphrasable worry is fog. (Ticket-vs-fog distinction: Pocock's wayfinder.)

Action Router

Parse the first token of $ARGUMENTS.

Argument	Action	When
(empty)	auto	Open map for the topic exists → work; else → chart
chart [topic]	Chart	Build or extend a decision map. Interactive only — refuses non-interactive sessions (charting burns assumptions that need a human)
work [#map]	Work	Pick one frontier item and drive it to resolution

Chart mode

Charting is a human-in-the-loop session. If the session is non-interactive (CLAUDE_CODE_REMOTE, claude -p, an autonomous loop), STOP and report that charting needs an interactive session — do not fabricate a map.

1. Survey + fog test. Ground in the effort (read any existing <memory_dir>/<slug>/, recent commits, the topic). Sort every uncertainty through the fog test: sharp → candidate decision item; foggy → Not-yet-specified prose.
2. Create or extend the map issue. On first use in a repo, verify the wayfind label taxonomy (work-map, wayfind: *, needs-human) is present — an unknown --label fails the create. Honor the consuming repository's declared label ownership. If it names a label-as-code source of truth, STOP and report the exact missing set to that owner; otherwise report the set and ask the user how labels are provisioned. Never create labels ad hoc from this skill. Then create one issue labelled bare work-map (+ any repo program labels). Body carries the five sections — Destination (where this is going once the fog clears) / Notes (durable pointers only — PRs, committed docs, prior items, external links; memory-tier <memory_dir>/ artifacts are checkout-local, so distill their relevant content inline instead of pointing at paths other readers cannot resolve) / Decisions-so-far (a pointer index — each resolved decision's home is its own item's resolution comment, never recopied here) / Not-yet-specified (fog, prose) / Out-of-scope. Template + exact gh calls: context/tracker-mechanics.md.
3. Create typed decision items as sub-issues of the map, one per sharp question. Type label sets the routing target and the default mode (below). Wire blocked-by edges where one decision genuinely gates another — never invent edges to impose false order.
4. Materialize the mode on each item at creation: HITL types (interview, design, prototype) get the needs-human label; research omits it (autonomous-capable); task is per-item. One mechanism — the presence/absence of needs-human — carries the mode; no parallel Mode: body field.
5. Hand off to work. Report the frontier (open, unblocked, unassigned items) and recommend /planning:wayfind work to start resolving.

Work mode

1. Session-start reclaim + map hygiene. Reclaim any of your own stale in-progress items (idempotent). Check the map's invariants: every closed decision has a Decisions-so-far pointer line; no item resolved-in-comment but still open. Fix violations before proceeding.

2. Compute the frontier. frontier = open ∧ zero OPEN blockers ∧ unassigned (a closed blocker no longer holds an item back — count open blockers, not the raw edge count). In a non-interactive session, further filter OUT needs-human items; if that empties the frontier, STOP with a truthful "all remaining decisions need a human" — never resolve a HITL item by standing in for the human.

3. Pick one and claim it (sibling claim model — @me assignee + claim-comment lease with comment-order collision check, no claim label; see context/tracker-mechanics.md).

4. Route by type — invoke the target skill directly; its own Q&A supplies the HITL loop:

   Type label	Mode	Routes to
   wayfind: research	autonomous-capable	/discovery:research (falls back to inline research if not installed)
   wayfind: interview	HITL	/planning:interview
   wayfind: design	HITL	/planning:design — or /event-storming:methodology / /event-storming:simulation when the item is domain/event-model work
   wayfind: prototype	HITL	/prototype:pressure-test (behaviour/feasibility) or /prototype:explore-directions (design/UX) — the item body says which
   wayfind: task	per-item	Direct decision-unblocking work — no feature code, no PR tie

5. Graduate on every resolution. When the decision resolves: post the resolution as a comment on the item, add its one-line pointer to the map's Decisions-so-far index, then close the item (comment → index → close, as one atomic sequence). If the resolution sharpened previously-foggy uncertainty, chart the new sharp items now.

6. Map closure → destination handoff. When the frontier is empty and every decision item is closed, the destination is coherent: close the map issue and hand the destination onward (/planning:interview or /planning:prd for a Brief/PRD; /planning:plan for a PLAN). A map's job ends where the pipeline's begins.

Escalation — pull the user back to charting at choke points

/wayfind's description carries the proactive trigger. The sibling skills carry pull-back lines: when /interview, /planning:plan, or /implement hits a task that is clearly too-big-AND-foggy for their stage, they name /planning:wayfind as the better entry — guiding the user, never auto-switching. Wording lives in each of those skills; this skill owns the trigger's meaning (too-big + fog, both, not either alone).

Composition

When	Skill	How it composes
Effort too big AND foggy to ticket	/planning:wayfind (this)	Produces a decision map; graduates to a destination
A single sharp contract to lock	/planning:interview	The map's interview-typed items route here; also the graduation target
Product intent still fuzzy	/planning:prd	Graduation target when the destination is a PRD
Design-space item	/planning:design, /event-storming:*	design-typed items route here
Feasibility / UX unknown	/prototype:pressure-test, /prototype:explore-directions	prototype-typed items route here
External-evidence item	/discovery:research	research-typed items route here (autonomous)
The plan itself	/planning:plan	Graduation target when the destination is a PLAN

What this skill does NOT do

• Does not do build work. A map holds decisions; build items live on the ordinary tracker (/work-items) after the map graduates. If a decision resolves into buildable work, that's a graduation, not a map item.
• Does not resolve a HITL item for the human. needs-human items are never resolved by an agent standing in for the user (inviolable). Non-interactive frontier filters them out.
• Does not chart non-interactively. Charting burns assumptions that need a human in the loop; the chart action refuses non-interactive sessions.
• Does not store coordination in the memory tier. The map (coordination) lives on the tracker; <memory_dir>/<slug>/ (default .work/) holds execution artifacts only (journals, research scratch, evidence).
• Does not invent a second claim/mode mechanism. Claims use the sibling /work-items model; mode is the needs-human label — no parallel taxonomy.

Reference

• context/tracker-mechanics.md — the gh commands for map creation, typed-item creation, edges, frontier query, and the claim protocol
• context/map-anatomy.md — the map body template, the five sections, and the graduation/closure invariants