wayfinder: reframe description around planning big work

The description does the skill's invocation work, so lead with the trigger
that actually reaches for Wayfinder — a huge chunk of work, more than one
agent session can hold — instead of the softer "chart a route through a
foggy problem". Skill body and fog-of-war mechanic unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.changeset/wayfinder-map-index.md

@@ -0,0 +1,7 @@
+---
+"mattpocock-skills": minor
+---
+
+Make **`wayfinder`**'s no-duplication contract explicit: the map is an **index**, not a store.
+
+Adopting "index" as the leading word for the map's role fixes two duplication risks. The map now states up front that a decision lives in exactly one place — its ticket — so it only ever gists and links, never restates the answer (previously this rule was implied inside an HTML comment in the map-body template). And graduating fog into a ticket now clears the graduated patch from the Fog, so a suspected question can't linger in both places at once.

.changeset/wayfinder-plan-big-work.md

@@ -0,0 +1,7 @@
+---
+"mattpocock-skills": minor
+---
+
+Reframe **`wayfinder`**'s description around the work it's for: planning a huge chunk of work, more than one agent session can hold.
+
+The description does the skill's invocation work, so it now leads with the trigger that actually reaches for Wayfinder — a big effort you need to break down — instead of the softer "chart a route through a foggy problem". The skill body and fog-of-war mechanic are unchanged.

skills/in-progress/README.md

@@ -8,3 +8,4 @@ Skills that are still being developed. They're not ready to ship — expect roug
 - **[writing-beats](./writing-beats/SKILL.md)** — Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end.
 - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article.
 - **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step.
+- **[claude-handoff](./claude-handoff/SKILL.md)** — Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked.

skills/in-progress/claude-handoff/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: claude-handoff
+description: Hand the current conversation off to a fresh background agent that picks up the work immediately.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff summary of the current conversation so a fresh agent can continue the work. Instead of saving it, launch a background agent seeded with the summary as its prompt: `claude --bg --name "<descriptive name>" "<handoff summary>"`. It starts in the current working directory and returns immediately; the user manages it with `claude agents`.
+
+Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"`) — it sets the display name shown in the job list, session picker, and terminal title.
+
+Include a "suggested skills" section in the summary, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information — the summary becomes the agent's prompt.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the summary accordingly.

skills/in-progress/wayfinder/SKILL.md

@@ -1,16 +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
+description: Plan a huge chunk of work — more than one agent session can hold — as 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.
 ---
 
 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.
 
-**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 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.
 
 ### The map body
 
@@ -18,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
-<!-- one context pointer per closed ticket — enough to judge relevance; zoom the link for detail -->
-- [<closed ticket title>](<link>) — <one-line gist of the answer>
+
+<!-- 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>
 
 ## Fog
+
 <!-- see "Fog of war" for what belongs here -->
 ```
 
@@ -34,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>
 ```
 
@@ -68,7 +78,7 @@ Fog excludes only what's already decided (that's Decisions so far) and what's al
 
 ## Invocation
 
-Two branches. 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
 
@@ -77,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
 
@@ -87,29 +97,6 @@ User invokes with a map (URL or number). A ticket is **optional** — without on
 2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: set `wayfinder:claimed` and save before any work.
 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. If the decision invalidates other parts of the map, update or delete those tickets.
-6. Handoff.
+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.
 
 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.