Compare commits

...
Author SHA1 Message Date
Matt PocockandClaude Opus 4.8 a12cca62fa wayfinder: use placeholders in Handoff example, drop no-op
Cut the "(trailing name orients you; it's ignored on paste)" gloss —
a # comment is self-evident. Replace the arbitrary "Briefing pipeline"
map name and specific ticket names with <map name>/<ticket name>
placeholders, consistent with the surrounding <map-url>/<issue-url>
style so nothing reads as a real referent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:28:42 +01:00
Matt PocockandClaude Opus 4.8 eb63f6e92c wayfinder: dedup identity claim in Refer-by-name
"id stays the identity" duplicated the Tickets section's "issue id is
its identity" — single source of truth belongs there (co-located with
the wiring/blocking mechanics that depend on ids). Reword to state the
pasteable-handle exception (link target, Handoff URL) without
re-defining identity. Trim redundant rationale wording.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:26:41 +01:00
Matt PocockandClaude Opus 4.8 ee014fa8b1 wayfinder: refer to maps and tickets by name, not id
Add a "Refer by name" convention so Wayfinder surfaces maps and
tickets by their human-friendly title in everything the human reads
(narration, Decisions-so-far, Handoff) rather than bare ids, numbers,
or slugs — a wall of #42, #43, #44 is illegible; names read at a
glance. The id/URL stays the identity and pasteable handle, riding
inside the name's link.

Update the Handoff example to demonstrate it: name the map in the
header and annotate each parallel command with its ticket name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 11:23:55 +01:00
Matt Pocock a5c124ef9c Made wayfinder model-invocable 2026-07-02 11:01:48 +01:00
Matt PocockandGitHub c6b033e93a Merge pull request #420 from mattpocock/wayfinder-branch-terminology
fix(wayfinder): rename "Two branches" to "Two modes"
2026-07-02 09:57:03 +01:00
+17 -7
View File
@@ -1,18 +1,21 @@
---
name: wayfinder
description: Chart a route through a foggy problem — turn a loose idea into a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the goal is clear.
disable-model-invocation: true
---
A loose idea has arrived — too big for one agent session, and wrapped in fog: the route from here to a plan isn't visible yet. This skill charts it as a **shared map** on the repo's issue tracker, then works its tickets one at a time. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
## Refer by name
Every map and ticket is an issue, so it has a **name** — its title. In everything the human reads — narration, the map's Decisions-so-far, the Handoff — 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, and Handoff commands still paste the URL — 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, labelled `wayfinder:map` — the canonical artifact. Its tickets are child issues of the map.
The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** Consult `docs/agents/issue-tracker.md` (the "Wayfinding operations" section) for how *this* repo expresses them. If that doc is absent, default to the local-markdown tracker.
**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** Consult `docs/agents/issue-tracker.md` (the "Wayfinding operations" section) for how _this_ repo expresses them. If that doc is absent, default to the local-markdown tracker.
### The map body
@@ -20,13 +23,17 @@ The whole map at low resolution, loaded once per session. Open tickets are **not
```markdown
## Notes
<domain; skills every session should consult; standing preferences for this effort>
## Decisions so far
<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
- [<closed ticket title>](<link>) — <one-line gist of the answer>
- [<closed ticket title>](link) — <one-line gist of the answer>
## Fog
<!-- see "Fog of war" for what belongs here -->
```
@@ -36,6 +43,7 @@ Each ticket is a **child issue** of the map; the tracker's issue id is its ident
```markdown
## Question
<the decision or investigation this ticket resolves>
```
@@ -100,18 +108,20 @@ End every session with a **Next steps** block the user can copy-paste. Two cases
**Open tickets remain.** Query the map for the currently-unblocked children, then give two copy-paste options: a bare command for one session (you pick the next ticket), and one pinned command per unblocked ticket for running them in parallel. Paste one line per fresh window — opening one, some, or all of them.
> **Next steps** — 3 tickets unblocked. Clear the context, then open fresh sessions.
> **Next steps** — *<map name>*: 3 tickets unblocked. Clear the context, then open fresh sessions.
>
> **One session** — resolves the next unblocked ticket:
>
> ```
> Invoke /wayfinder with the map <map-url>.
> ```
>
> **Parallel** — paste one line per window, up to all 3:
>
> ```
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>.
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>.
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>.
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>. # <ticket name>
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>. # <ticket name>
> Invoke /wayfinder with the map <map-url>, ticket <issue-url>. # <ticket name>
> ```
**No open tickets remain.** The fog is pushed back far enough that the way to the goal is clear — the map is done. (The initial grilling may also surface no fog at all, in which case there was never a map to chart.) Recommend implementing directly, or using `/to-prd` to schedule a multi-session implementation.