wayfinder · Skill Details

Mechanism

When It Triggers · How It Works · What It Produces

Breaks down how the skill works and what it produces, so you can quickly judge whether it fits your scenario and value.

Trigger: User-invoked for efforts spanning multiple agent sessions with unclear paths. /ask-matt lists it as one of the on-ramps, calling it "the most cognitively demanding flow." Transitions to /to-spec once the path clears.
Mechanism: Two modes: (1) Chart the map — first grilling to name the destination, breadth-first scan fog, create the map issue (wayfinder:map label), create ticketable questions as child issues, wire blocking edges (frontier = open, unblocked, unclaimed), research tickets resolved in parallel by background agents; (2) Work through the map — load the map, pick the first frontier ticket, claim it, resolve it (zoom on demand), record the resolution (comment + close + append to Decisions so far), update fog of war. One ticket per session (except research). 4 ticket types: Research (AFK), Prototype (HITL), Grilling (HITL), Task (HITL or AFK).
Output: An evolving decision map, resolved one ticket at a time until the destination is visible. Produces decisions, not deliverables, then transitions to /to-spec for buildable plan consolidation.

Use Cases

Two Typical Use Cases

Scenario 01

Path planning for a large greenfield project

A team building a new SaaS platform involving payment, subscriptions, multi-tenancy — far exceeding one agent session. Invoking `/wayfinder`, the skill uses grilling and domain-modeling to name the "destination" (a shippable MVP), then breadth-first scans the space, charting the fog of war. Sharply defined questions become tickets immediately (research tickets resolved in parallel by background agents); imprecise ones stay in "Not yet specified." Each subsequent session resolves one ticket until the path is clear.

Scenario 02

Navigating a complex migration project

A team splitting a monolith into microservices faces database splitting, API redesign, and traffic migration. Invoking `/wayfinder` charts a decision map. The grilling phase identifies "database shard key selection" as a critical blocking decision, creating both a research and a prototype ticket to investigate and validate. Once all tickets are resolved and the path is clear, the effort transitions to `/to-spec` for consolidation into a buildable plan.

Skill Relationships

Which Skills I Use · Which Skills Use Me

Dependency relationships read as "the upper tier points to the lower tier." The current Skill sits in the middle tier — above are Skills that depend on it, below are Skills it depends on.

Tier 1 · These Skills Use Me

ask-mattWorkflow

Tier 2 · Current Skill

wayfinderWorkflow

Tier 3 · I Use These Skills

Full Relationship Graph

Browse this skill's relationships within its skillset. Click a node to switch the side panel; use the search box to jump to any skill.

Skill File

SKILL.md

Open in GitHub ↗

SKILL.mdLoading from GitHub…

Skill Composition

Open in GitHub ↗

SKILL.md50.0%
other50.0%

▸skills/wayfinder/
▸wayfinder
- ·SKILL.md
- ▸agents
  - ·openai.yaml

Per the Agent Skills spec, SKILL.md is the only required file. The colored bars classify the rest into the three spec-aligned optional directories (scripts / references / assets) and an 'other' bucket. The full directory tree is below.

Related in Skillset

You May Also Need These Skills

ask-matt

A router skill for the entire skillset: when the user can't remember which skill to use or which flow fits their situation, they invoke this to get a recommendation. It describes the main "idea → ship" flow (grill-with-docs → to-spec/to-tickets → implement), plus on-ramps (triage, diagnosing-bugs, wayfinder), codebase health (improve-codebase-architecture), vocabulary layers (domain-modeling, codebase-design), and standalone skills (grill-me, prototype, research, teach). Following its map leads users to the correct workflow entry point.

Workflow

code-review

A two-axis code review skill: reviews a diff (from a fixed point to HEAD) along both Standards (coding standards + Fowler smell baseline) and Spec (faithful implementation of the originating issue/PRD). Both axes run as parallel sub-agents to avoid context pollution. The report aggregates findings without merging conclusions, ensuring "passes standards but implements the wrong thing" and "implements the right thing but breaks conventions" are both surfaced independently.

Workflow

codebase-design

A shared vocabulary skill for deep module design: provides a precise set of design terms (Module, Interface, Depth, Seam, Adapter, Leverage, Locality) guiding agents and developers to design "deep modules" — a lot of behaviour behind a small interface. Includes design principles (the deletion test, the interface is the test surface) and testability guidelines. A reference skill consumed by other skills (e.g., improve-codebase-architecture, tdd) and invoked directly by engineers.

Style Guide

diagnosing-bugs

A disciplined diagnosis loop for hard bugs and performance regressions. The core idea is to first build a tight feedback loop — no hypothesis phase without one. Six phases: build feedback loop → reproduce + minimise → generate 3-5 falsifiable hypotheses → instrument by prediction → fix + regression test → cleanup + post-mortem. If the codebase architecture can't lock down the bug, it recommends handing off to the improve-codebase-architecture skill.

Workflow