A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the destination isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a shared map on the repo's issue tracker, then works its issues one at a time until the route is clear.

The destination varies per effort, and naming it is the first act of charting — it shapes every issue. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.

Plan, don't do

Wayfinder is planning by default: each issue resolves a decision, and the map is done when the way is clear — nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off. An effort can override this in its Notes — carrying execution into the map itself — but absent that, produce decisions, not deliverables.

Refer by name

The map and every child are tracker issues, so each has a name — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name, never by a bare id, number, or slug. A wall of #42, #43, #44 is illegible; names read at a glance. The id and URL don't vanish — a name wraps its link — but they ride inside the name, never stand in for it.

The Map

The map is a single issue on this repo's issue tracker — the canonical artifact. Mark it with wayfinder:map where the tracker supports labels; local Markdown uses type: wayfinder-map. Its investigations are child issues of the map.

The map is an index, not a store. It lists the decisions made and points at the issues that hold their detail; a decision lives in exactly one place — its issue — so the map never restates it, only gists it and links.

Where the map, its child issues, blocking, and frontier queries physically live is tracker-specific. The issue tracker must have been provided to you. If it is missing, stop and ask the user to run /setup-agent-skills; that setup defaults to existing Beads state, then local .scratch, and never infers a hosted tracker from the Git remote. Consult the tracker doc's "Wayfinding operations" section for how this repo expresses them.