Compare commits

...
Author SHA1 Message Date
Matt PocockandClaude Opus 4.8 1f16ea9499 wayfinder: remove the Handoff ceremony
Every session ended with a Handoff that queried the frontier and emitted
per-ticket copy-paste commands — real token cost each session. Cut it
entirely and let the natural flow carry continuation: the next
/wayfinder session already loads the map and picks the next frontier
ticket, so nothing is lost, just deferred to re-invocation.

Reconciles the references left behind: the one-ticket-per-session rule
and "charting is one session's work" constraint survive as plain lines;
the Refer-by-name paragraph drops its Handoff mentions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 13:48:13 +01:00
Matt PocockandGitHub a83f22b60f Merge pull request #421 from mattpocock/add-claude-handoff-skill
Add claude-handoff skill (in-progress)
2026-07-02 11:33:48 +01:00
Matt PocockandGitHub e0d0d84274 Merge pull request #422 from mattpocock/wayfinder-refer-by-name
wayfinder: refer to maps and tickets by name, not id
2026-07-02 11:31:36 +01:00
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
+6 -27
View File
@@ -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 — 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 — 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.
@@ -74,7 +78,7 @@ Fog excludes only what's already decided (that's Decisions so far) and what's al
## Invocation
Two modes. Either way, **every session ends with a [Handoff](#handoff)**never resolve more than one ticket per session.
Two modes. Either way, **never resolve more than one ticket per session.**
### Chart the map
@@ -83,7 +87,7 @@ User invokes with a loose idea.
1. Run a `/grilling` and `/domain-modeling` session to surface the open decisions.
2. **Create the map** (label `wayfinder:map`): Notes filled in, Decisions-so-far empty, Fog sketched.
3. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the Fog.
4. Handoff. Charting the map is one session's work; do not also resolve tickets.
4. Stop — charting the map is one session's work; do not also resolve tickets.
### Work through the map
@@ -94,30 +98,5 @@ User invokes with a map (URL or number). A ticket is **optional** — without on
3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from the Fog so it lives only as its new ticket. If the decision invalidates other parts of the map, update or delete those tickets.
6. Handoff.
The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.
## Handoff
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.
>
> **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>.
> ```
**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.