From ee014fa8b13939195e0fe4f4c6310b5737569338 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 2 Jul 2026 11:23:55 +0100 Subject: [PATCH 1/3] wayfinder: refer to maps and tickets by name, not id MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- skills/in-progress/wayfinder/SKILL.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/skills/in-progress/wayfinder/SKILL.md b/skills/in-progress/wayfinder/SKILL.md index 17b356d..a70895a 100644 --- a/skills/in-progress/wayfinder/SKILL.md +++ b/skills/in-progress/wayfinder/SKILL.md @@ -5,6 +5,10 @@ description: Chart a route through a foggy problem — turn a loose idea into a 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 at a glance; names read instantly. The id and URL stay the identity: the link a name wraps, the pasteable handle in a command — 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. @@ -104,7 +108,7 @@ 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** — *Briefing pipeline*: 3 tickets unblocked. Clear the context, then open fresh sessions. > > **One session** — resolves the next unblocked ticket: > @@ -112,12 +116,12 @@ End every session with a **Next steps** block the user can copy-paste. Two cases > Invoke /wayfinder with the map . > ``` > -> **Parallel** — paste one line per window, up to all 3: +> **Parallel** — paste one line per window, up to all 3 (trailing name orients you; it's ignored on paste): > > ``` -> Invoke /wayfinder with the map , ticket . -> Invoke /wayfinder with the map , ticket . -> Invoke /wayfinder with the map , ticket . +> Invoke /wayfinder with the map , ticket . # Reciprocity filter +> Invoke /wayfinder with the map , ticket . # TTS chunking +> Invoke /wayfinder with the map , ticket . # Voice selection > ``` **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. From eb63f6e92c1458128c84c3eff32a9d72ba6a1b8c Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 2 Jul 2026 11:26:41 +0100 Subject: [PATCH 2/3] wayfinder: dedup identity claim in Refer-by-name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "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) --- skills/in-progress/wayfinder/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/in-progress/wayfinder/SKILL.md b/skills/in-progress/wayfinder/SKILL.md index a70895a..3790a28 100644 --- a/skills/in-progress/wayfinder/SKILL.md +++ b/skills/in-progress/wayfinder/SKILL.md @@ -7,7 +7,7 @@ A loose idea has arrived — too big for one agent session, and wrapped in fog: ## 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 at a glance; names read instantly. The id and URL stay the identity: the link a name wraps, the pasteable handle in a command — they ride *inside* the name, never stand in for it. +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 From a12cca62fa4e63ee7b2fb6b955600789e6dedf63 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Thu, 2 Jul 2026 11:28:42 +0100 Subject: [PATCH 3/3] wayfinder: use placeholders in Handoff example, drop no-op MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 / placeholders, consistent with the surrounding / style so nothing reads as a real referent. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/in-progress/wayfinder/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/in-progress/wayfinder/SKILL.md b/skills/in-progress/wayfinder/SKILL.md index 3790a28..7f1b8b3 100644 --- a/skills/in-progress/wayfinder/SKILL.md +++ b/skills/in-progress/wayfinder/SKILL.md @@ -108,7 +108,7 @@ 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** — *Briefing pipeline*: 3 tickets unblocked. Clear the context, then open fresh sessions. +> **Next steps** — **: 3 tickets unblocked. Clear the context, then open fresh sessions. > > **One session** — resolves the next unblocked ticket: > @@ -116,12 +116,12 @@ End every session with a **Next steps** block the user can copy-paste. Two cases > Invoke /wayfinder with the map . > ``` > -> **Parallel** — paste one line per window, up to all 3 (trailing name orients you; it's ignored on paste): +> **Parallel** — paste one line per window, up to all 3: > > ``` -> Invoke /wayfinder with the map , ticket . # Reciprocity filter -> Invoke /wayfinder with the map , ticket . # TTS chunking -> Invoke /wayfinder with the map , ticket . # Voice selection +> Invoke /wayfinder with the map , ticket . # +> Invoke /wayfinder with the map , ticket . # +> Invoke /wayfinder with the map , ticket . # > ``` **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.