Wayfinder: Map Decisions Across Sessions

What it does

The canonical map is an issue that states a destination, keeps a compact index of resolved decisions and distinguishes unspecified in-scope questions from exclusions. Child issues hold the actual decision detail. Research, prototype, grilling and prerequisite-task tickets have different execution needs; human discussion cannot be replaced by invented answers. Native tracker blocking relationships reveal the available frontier. Planning is the default: once the route is clear, the workflow hands off rather than silently building the product.

When to use it

• Resolve architecture and product uncertainty before a large platform migration.
• Carry a research-heavy initiative across multiple sessions.
• Separate genuinely unknown decisions from work explicitly excluded.

Step-by-step workflow

1. Name the destination with the human and define the scope.
2. Chart precise current questions and leave vague future questions in the map’s unspecified section.
3. Create the map and child tickets, then wire dependencies using real identities.
4. Claim an unblocked ticket and resolve it according to its research or human-interaction type.
5. Record the resolution in its ticket, update the map’s index and reveal newly precise questions.

Example request

Use wayfinder to plan our migration from batch invoices to event-driven processing. The destination is an agreed migration design, not production code. Separate delivery guarantees, historical replay and cutover decisions. Keep billing-provider replacement out of scope. Propose a local map first. Do not create external issues, launch research agents, provision services or perform migrations without separate authorization.

Worked example

A delivery-guarantee question can block the replay strategy, while unrelated user-interface preferences may remain outside the destination. Resolving delivery guarantees should place the detailed answer in that ticket and only a short linked gist in the map. A vague concern about operations can remain unspecified until the replay decision makes a precise question possible. Closing every planning ticket establishes a route, not evidence that invoices have migrated. The next step is usually specification and implementation planning.

What you get

A navigable decision map with linked resolutions, an actionable frontier and explicit exclusions.

How to evaluate the result

• Check detailed decisions live once in their own tickets.
• Verify the frontier excludes blocked or claimed work.
• Confirm the map ends at its agreed destination rather than expanding indefinitely.

What you need

A destination owner, tracker operations or local-markdown fallback, dependency support and companion skills. Upstream research tickets use subagents; human tickets need a real participant.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

Overhead is unsuitable for a small settled feature. The source normally resolves one non-research ticket per session. Tracker writes, pushed research branches and provisioning tasks require their own authorization; a planning invocation does not erase those boundaries.

Related workflows

• Use to-spec when the decision map is clear.
• Use prototype for questions that need a concrete artifact.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Reviewed SKILL.md (immutable commit)
• Publisher README: setup and compatibility
• Reviewed MIT license