wayfinder

Files (3)

• LICENSE
• SKILL.md
• frontier.sh · scripts/

SKILL.md (first lines)

<!-- 本檔在契約測試底下：python3 ~/.claude/commands/tests/test_skill_verify_one_shot_callers.py -->

# 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 **map** of **decision tickets** — questions whose resolution is a decision, not slices of a build to execute — and works them 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, a decision to lock before planning starts, or a change made in place like a data-structure migration.

## Plan, don't do

Wayfinder is **planning** by default: each ticket resolves a decision, and the map is done when the way is clear — nothing left to decide before someone goes and builds. 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 to /to-spec. An effort can override this in the map's **Notes**, but absent that, produce decisions, not deliverables.

## Refer by name

Every ticket has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far — refer to it by that name wrapped around its file link, never by a bare number or path. A wall of `#42, #43, #44` is illegible; names read at a glance.

## The board (local landing)

The board is a directory, landed by the repo's convention (same adaptive rule as /to-spec and /to-tickets):

- Repo has `openspec/` → `openspec/changes/<effort-slug>/wayfinder/` — so when the map clears, /to-spec lands the spec in the same change dir.
- Otherwise → `.scratch/<effort-slug>/wayfinder/`

```
wayfinder/
├── map.md            (the canonical low-res view)
└── tickets/
    └── NNN-<kebab-name>.md
```

### map.md

The whole effort at low resolution, loaded once per session. Open tickets are **not** listed here — they are found by scanning `tickets/`. The map is an **index**, not a store: a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.

```markdown
## Destination

<what reaching the end looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

## Notes

<domain; skills or conventions every session should consult; standing preferences for this effort>

## Decisions so far

- [<closed ticket name>](tickets/NNN-name.md) — <one-line gist of the answer>

## Not yet specified

<!-- see "Fog of war": in-scope fog you can't ticket yet -->

## Out of scope

<!-- work ruled beyond the destination; never graduates -->
```

### Tickets

Each ticket is one file, `tickets/NNN-<kebab-name>.md`, sized to one agent session:

```markdown
---
status: open | claimed | closed
type: research | prototype | grilling | task
blocked-by: [NNN, NNN]
---

## Question

<the decision or investigation this ticket resolves>

## Resolution

<written on close: the answer, plus links to any assets created>
```

A session **claims** a ticket by setting `status: claimed` **first**, before any work. A ticket is **unblocked** when every ticket in its `blocked-by` is closed; the **frontier** is the open, unblocked tickets — the edge of the known. List it with `scripts/frontier.sh <board-dir>`.

Assets created while resolving (research files, mockups) are linked from the ticket, not pasted in.

## Ticket types

Every ticket is either **HITL** — human in the loop, worked *with* the user — or **AFK**, driven by the agent alone. A HITL ticket only resolves through live exchange; the agent never stands in for the user's side of it (a grilling session that answers its own questions has broken this — the questioning discipline already in context applies).

- **Research** (AFK): reading documentation, third-party APIs, codebases, or the user's own knowledge base to surface a fact a decision waits on. Resolve by dispatching a background research agent with a fresh context window per the routing rules already in context; the agent leaves a cited findings file linked from the ticket.
- **Prototype** (HITL): raise the fidelity of the discussion with a cheap, rough, concrete artifact to react to. Resolve via the /prototype skill — it picks the branch (single shareable HTML file for logic/state questions, structurally different UI variants behind a URL param for looks questions) and defines the capture protocol. Use when "how should it look / behave" is the key question.
- **Grilling** (HITL): interview the user — one question at a time, each with a recommended answer; asking several at once is bewildering. Look up facts the environment can answer (filesystem, git, docs) instead of asking; the decisions are the user's — put each one to them and wait, never answering in their place. Propose /grill-me when the decision tree is deep; invoke /domain-modeling when a term turns out fuzzy or a resolution deserves a decision record. The default type.
- **Task** (HITL or AFK): manual work that must happen before a decision can be made — provisioning access, signing up for a service, moving data so its shape can be seen. The one type that *does* rather than decides, earning its place by unblocking a decision. The agent drives it alone where it can; otherwise it hands the user a precise numbered checklist. The resolution records what was done and any resulting facts (credential locations, URLs, counts) later tickets depend on.

## Fog of war

The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the live tickets lies the **fog of war** — decisions you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets — until the way is clear and no tickets remain.

The map's **Not yet specified** section holds that dim view: the suspected question, the area to revisit. **Fog or ticket?** The test is whether you can state the question precisely now — _not_ whether you can answer it now. Ticket when the question is sharp (even if blocked); fog when you can't phrase it that sharply. Don't pre-slice fog into ticket-sized pieces — one patch may graduate into several tickets, or none.

## Out of scope

The destination fixes the scope, so work beyond it is **out of scope** — it isn't fog and doesn't belong in Not-yet-specified. When an existing ticket turns out to sit past the destination, **close it** and leave one line in Out of scope: the gist, why it's out, linking the closed ticket. It stays out of Decisions-so-far, which records the route actually walked. Out-of-scope work never graduates; it returns only if the destination is redrawn, as a fresh effort.

## Invocation

This skill is a local decision-map aid. When the map clears, hand off to the local chain (`to-spec` → `to-tickets` → `implement`).

Two modes. Either way, resolve one ticket per session by default — one decision at a time is what keeps the reasoning sharp and the resolution auditable, not a context-size limit. Batch only when the user asks.

### Chart the map

User invokes with a loose idea, or accepts the proposal after a requirements gate reports wayfinder-scale fog.

0. Confirm the user has explicitly agreed to chart a map (they typed /wayfinder, or said yes to a proposal). If not, propose it with a one-line cost warning — charting is a full session of interviewing — and stop. Done when: explicit user go-ahead is on record.
1. **Name the destination.** Interview per the questioning discipline in context to pin down what this map is finding its way to. Done when: the user has confirmed a one-or-two-line destination.
2. **Map the frontier.** Interview again, **breadth-first**: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way is already clear, the journey small enough for one session — stop, tell the user a map isn't needed, and route to /to-spec or direct work instead. Done when: open decisions and fog patches are listed and the user confirms nothing major is missing, or the no-fog exit fired.
3. **Create the board**: map.md with Destination and Notes filled in, Decisions-so-far empty, fog sketched into Not yet specified. Done when: map.md exists with all five sections.
4. **Create the tickets you can specify now**, then wire `blocked-by` in a **second pass** (tickets need numbers before they can reference each other). Everything you can't yet specify stays in the fog. Done when: every sharp question has a ticket file and blocking edges are wired.
5. **Fire the research agents.** For each research ticket, dispatch a background agent with a fresh context window per the routing rules in context, pointing its findings file back at the ticket. Done when: every research ticket has an agent dispatched, or a stated reason to defer.
6. **Self-Verify** (mandatory — board written, before presenting). Dispatch an `Agent` with `subagent_type: skill-verify-auditor` (sonnet+low, Read-only, pinned in the agent definition), description containing the marker string `skill-verify:wayfinder` (statistics grep — keep verbatim)。

   **Prompt 要內嵌 board 全文，不要給目錄路徑。** 兩個理由：

From GGGODLIN/gggodlin-cc-harness, MIT.

More from GGGODLIN/gggodlin-cc-harness