wayfinder

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 in the repo's Markdown files, then works its decision tickets (questions whose resolution is a decision, not slices of a build to execute) 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 ticket. 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: each ticket resolves a decision, and the map is done when the way is clear, with 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. This is optional discovery before either the Light or Heavy track; the effort's Notes do not authorize production implementation. Keep findings local; commits, publication, merging, and worktree cleanup belong to the user.

Refer by name

Every map and ticket is a Markdown file with 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. A name wraps a relative link to the file; the path never stands in for the name.

The Map

The map is docs/specs/<effort>/map.md, the canonical index for this effort. Its tickets are files under docs/specs/<effort>/decisions/; research notes and rough assets live under docs/specs/<effort>/research/ and docs/specs/<effort>/assets/. Create directories only when needed. Use one effort directory per destination and reuse it when resuming.

The map is an index, not a store. It lists the decisions made and points at the tickets that hold their detail; the map never restates that detail, only gists it and links. If domain-modeling records a term in GLOSSARY.md or a durable decision in docs/adr/, the ticket links to that canonical source instead of copying it. Implementation plans remain numbered documents under docs/plans/ in the Heavy track.

Local file operations are defined below. Read and update these Markdown files directly; this skill needs no external issue service or setup skill.