feat(wayfinder): run research inline as a subagent, not as a ticket

Research is fully AFK and yields a fact, not a decision, so it never
earns a ticket's session boundary. Drop `research` from the
`wayfinder:<type>` set and reframe it as inline fuel: any session
spins up a `/research` subagent the moment it hits a knowledge gap,
captures the findings on a throwaway `research/<name>` branch, and
leaves a context pointer on the ticket it informs (or the map's Notes).

Updates the SKILL, the GitHub/GitLab/local tracker type lists, and the
docs page, plus a changeset.

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

.changeset/wayfinder-research-inline.md

@@ -0,0 +1,5 @@
+---
+"mattpocock-skills": minor
+---
+
+Reframe how **`wayfinder`** handles research: it's no longer a ticket type — it runs **inline as a subagent**. Research is fully AFK (no human gates it) and produces a *fact*, not a decision, so it never earns a ticket's session boundary. Instead, any session — charting or resolving — spins up a `/research` subagent the moment it hits a knowledge gap, keeps working while it reads, and folds the findings straight into the decision it's making. The findings are captured as a primary source on a throwaway `research/<name>` branch (mirroring how `/prototype` captures prototypes), with a context pointer left on the ticket the research informs, or in the map's Notes if it informs the whole effort. Drops `research` from the `wayfinder:<type>` label set (`prototype`/`grilling`/`task`) across the GitHub, GitLab, and local trackers, and re-syncs the docs page.

docs/engineering/wayfinder.md

@@ -30,7 +30,7 @@ The **map** is a single `wayfinder:map` issue whose tickets are its child issues
 
 Beyond the live tickets lies the **fog of war** — decisions you can tell are coming but can't yet pin down. The test for whether something is a ticket or still fog is whether you can *state the question precisely now*, not whether you can answer it. Resolving a ticket clears the fog ahead of it, **graduating** whatever's now specifiable into fresh tickets. The **frontier** is the open, unblocked, unclaimed tickets — the edge of the known — and it's what the tracker's native blocking renders visually, so you see what's takeable without opening the map. Fog only gathers *toward* the **destination**; work past it is ruled **out of scope**, closed, never graduating.
 
-Every ticket is **HITL** (human in the loop — grilling, prototype) or **AFK** (agent alone — research); a HITL ticket only resolves through a live exchange, so the agent never answers its own questions.
+Every ticket is **HITL** (human in the loop — grilling, prototype) or an agent-driven **task**; a HITL ticket only resolves through a live exchange, so the agent never answers its own questions. Research is deliberately **not** a ticket: it's fully AFK and yields a fact, not a decision, so any session spins up a `/research` subagent inline the moment it needs external knowledge — capturing the findings on a throwaway `research/<name>` branch and leaving a context pointer on the ticket it informs — rather than parking a separate ticket for a later session to open, read, and close.
 
 ## It's working if
 
@@ -41,4 +41,4 @@ Every ticket is **HITL** (human in the loop — grilling, prototype) or **AFK**
 
 ## Where it fits
 
-`wayfinder` is a big-idea **on-ramp**: an effort too large and foggy to spec in one sitting generates a cleared map of decisions, which then merges onto the main build flow. When the fog is pushed back and the way is clear, hand off to [to-spec](https://aihero.dev/skills-to-spec) to schedule the multi-session build (or, if the effort turned out small, implement directly). It leans on [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) to resolve individual tickets, and on [prototype](https://aihero.dev/skills-prototype) and [research](https://aihero.dev/skills-research) for the ticket types that need them. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.
+`wayfinder` is a big-idea **on-ramp**: an effort too large and foggy to spec in one sitting generates a cleared map of decisions, which then merges onto the main build flow. When the fog is pushed back and the way is clear, hand off to [to-spec](https://aihero.dev/skills-to-spec) to schedule the multi-session build (or, if the effort turned out small, implement directly). It leans on [grilling](https://aihero.dev/skills-grilling) and [domain-modeling](https://aihero.dev/skills-domain-modeling) to resolve individual tickets, on [prototype](https://aihero.dev/skills-prototype) for the tickets that need a concrete artifact, and on [research](https://aihero.dev/skills-research) as an inline subagent whenever a decision needs external facts. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.

skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md

@@ -38,7 +38,7 @@ Run `gh issue view <number> --comments`.
 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
 
 - **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
-- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
 - **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
 - **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
 - **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.

skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -39,7 +39,7 @@ Run `glab issue view <number> --comments`.
 Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
 
 - **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
-- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
 - **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
 - **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
 - **Claim**: `glab issue update <n> --assignee @me` — the session's first write.

skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md

@@ -23,7 +23,7 @@ Read the file at the referenced path. The user will normally pass the path or th
 Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
 
 - **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
-- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
 - **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
 - **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
 - **Claim**: set `Status: claimed` and save before any work.

skills/engineering/wayfinder/SKILL.md

@@ -62,7 +62,7 @@ Each ticket is a **child issue** of the map; the tracker's issue id is its ident
 <the decision or investigation this ticket resolves>
 ```
 
-Each ticket carries a `wayfinder:<type>` label — one of `research`, `prototype`, `grilling`, `task` (see [Ticket Types](#ticket-types)).
+Each ticket carries a `wayfinder:<type>` label — one of `prototype`, `grilling`, `task` (see [Ticket Types](#ticket-types)). Research is deliberately _not_ a ticket type: it's AFK fuel a session runs inline, never a stop on the route (see [Research runs inline, not as a ticket](#research-runs-inline-not-as-a-ticket)).
 
 A session **claims** a ticket by assigning it to the dev driving the map, **first**, before any work, so concurrent sessions skip it. That assignee _is_ the claim: an open, unassigned ticket is unclaimed.
 
@@ -72,13 +72,24 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 
 ## Ticket Types
 
-Every ticket is either **HITL** — human in the loop, worked *with* a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
+A ticket exists because someone has to sit with it — so every ticket is either **HITL** (human in the loop, worked *with* a human who speaks for themselves) or a **task** the agent must drive by hand. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
 
-- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases. Creates a markdown summary as a linked asset. Use when knowledge outside the current working directory is required.
 - **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
 - **Grilling** (HITL): Conversation via the /grilling and /domain-modeling skills, one question at a time. The default case.
 - **Task** (HITL or AFK): Manual work that must happen before a *decision* can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that *does* rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
 
+## Research runs inline, not as a ticket
+
+Research — reading docs, third-party APIs, source, or local knowledge bases to gather facts — is **fully AFK**: no human gates it, and it produces a *fact*, not a decision. That combination is exactly why it must **not** be its own ticket. A ticket earns its place as a session boundary: a self-contained unit some *later* session claims and works. Research needs no such boundary — any session, charting or resolving, can spin up a research **subagent** (`/research`) the moment it hits a knowledge gap, keep working while it reads, and fold the findings straight into the decision it's making. Parking research as a ticket only forces a second session to open it, do the AFK read, and close it — a session boundary bought for nothing.
+
+So there is no research ticket and no research assignee. When a decision needs external knowledge:
+
+1. **Launch a research subagent inline** via `/research`, scoped to the specific question. Charting can do this to sharpen the destination or the frontier; resolving can do it to answer the ticket in hand.
+2. **Capture the findings as a primary source**, the way `/prototype` captures a prototype: commit the research Markdown to a **throwaway branch** out of main (`research/<name>`), so main stays clean but the reading stays findable.
+3. **Leave a context pointer** to that branch — on the ticket whose decision the research informs, or, if it informs the whole effort rather than one ticket, in the map's **Notes**. The pointer is a link, never a paste; the map stays an index.
+
+A blocked ticket that used to wait on a "research ticket" now simply carries, in its own body, the note that resolving it starts with a research subagent — the read happens inside that ticket's session, not as a prerequisite ticket before it.
+
 ## 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** — the dim view of decisions and investigations 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 — one at a time, until the way to the destination is clear and no tickets remain.
@@ -109,7 +120,7 @@ Two modes. Either way, **never resolve more than one ticket per session.**
 User invokes with a loose idea.
 
 1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
-2. **Map the frontier.** Grill again, **breadth-first** this time: 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 to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
+2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. Where a gap is a knowledge gap, resolve it with an inline `/research` subagent rather than charting a ticket for it (see [Research runs inline, not as a ticket](#research-runs-inline-not-as-a-ticket)). **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
 4. **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 — the **Not yet specified** section.
 5. Stop — charting the map is one session's work; do not also resolve tickets.
@@ -120,7 +131,7 @@ User invokes with a map (URL or number). A ticket is **optional** — without on
 
 1. Load the **map** — the low-res view, not every ticket body.
 2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself 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`.
+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 the ticket needs external knowledge, spin up a `/research` subagent inline and fold its findings in (see [Research runs inline, not as a ticket](#research-runs-inline-not-as-a-ticket)) — don't hand the reading off to a separate session. 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 **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.