An idea arrived too big for one session and wrapped in fog: the way to the destination is not visible yet. Chart that way as a map on the issue tracker, then resolve its decision tickets one session at a time until the route is clear. The skill finds the way; it never walks it.
Contract
Inputs:
- A loose idea (chart mode), or a map issue number or URL (work mode)
- The repo's tracker config (
docs/agents/issue-tracker.md) when present
Outputs:
- Chart mode: a map issue and its first decision tickets
- Work mode: one resolved ticket, the map updated, and the next frontier named
- When the way is clear: a recommendation to run
/prd prepareon the settled decisions
Creates/Modifies:
- GitHub issues: the map (label
wayfinder:map), child tickets (labelwayfinder:<type>), assignments, blocking links, resolution comments
External Side Effects:
- GitHub writes only. No code, no branches, except a throwaway
research/<name>branch a research ticket may use
Confirmation Required:
- Before publishing the map and its tickets: show destination, tickets and fog first, and confirm when the repo is public
- Invoking work mode on a map authorizes the claim, resolution comment, close and map update for one ticket; creating, updating or deleting any other ticket needs separate approval
Delegates To:
- Run the
grill-meanddomain-modelingskills for grilling tickets and for naming the destination - Run the
researchskill for research tickets - Run the
prototypeskill for prototype tickets - Recommend
prd-dispatchto turn the finished map into a feature issue - Recommend
show-me-your-workfor a long unattended run across tickets
Plan, don't do
Each ticket resolves a decision, and the map is done when nothing is left to
decide before someone goes and builds. The pull to just do the work marks the
edge of the map: hand off there. An effort may override this in its Notes.
Tickets are decisions, never build slices; the build is one feature issue that
/prd prepare writes from the settled map.
The map
One issue labelled wayfinder:map; its tickets are child issues. The map is an
index: it gists each decision and links the ticket that holds the detail, so a
decision lives in exactly one place. Refer to every map and ticket by its title,
never a bare number; the link rides inside the name.
## Destination
<what reaching the end looks like: the spec, decision or change; one or two lines>
## Notes
<domain, skills every session should consult, standing preferences>
## Decisions so far
- [<closed ticket title>](link): <one-line gist of the answer>
## Not yet specified
<fog: in-scope questions too dim to ticket yet>
## Out of scope
<work ruled beyond the destination, each with its reason; never graduates>
Open tickets stay out of the map: they are the open child issues, found by query.
Child links use the repo's native sub-issue API (see prd-task-creator's
independently-complete-children guide for the REST calls). Blocking uses the
native blocked-by relationship so the tracker's own view shows the frontier; fall
back to a Blocked by: body line only when the tracker lacks it, and say so. A
ticket is unblocked when every blocker is closed. The frontier is the
open, unblocked, unclaimed tickets. A session claims a ticket by assigning it
to the driver before any work.
Each ticket body is one ## Question, sized to one session. The answer is
recorded on resolution, not in the body.
Ticket types
HITL tickets resolve only through a live exchange; the agent never answers its own questions for the human.
| Type | Mode | Resolved by |
|---|---|---|
research |
AFK | the research skill, for facts outside the working directory |
prototype |
HITL | the prototype skill: a cheap artifact to react to, linked as an asset |
grilling |
HITL | grill-me plus domain-modeling; the default |
task |
either | doing the manual step a decision waits on (sign up, provision, move data); the answer records what was done and what later tickets depend on |
Fog of war
Chart only what you can see. Not yet specified holds the dim view: questions you can tell are coming but cannot yet phrase sharply. The test is whether you can state the question precisely now, not whether you can answer it now. Sharp but blocked is a ticket. Too dim to phrase is fog; do not pre-slice it. Resolving a ticket graduates the fog it cleared into new tickets.
Work beyond the destination is out of scope, not fog. Close a ticket that turns out to sit past the destination and leave one line in Out of scope: the gist, the reason, the link. Keep it out of Decisions so far.
Chart mode
- Name the destination. Run
grill-meanddomain-modelinguntil the destination is one or two lines. It fixes the scope. - Map the frontier. Grill again breadth-first: the open decisions and the first takeable steps. When no fog appears and one session can hold the whole journey, stop and say no map is needed.
- Show the plan: destination, tickets, fog. On confirmation, create the map, then the tickets, then wire blocking in a second pass (ids exist only after creation).
- Start each new
researchticket's resolution in a parallel subagent.
Done when the map and its first tickets exist and nothing was resolved by hand.
Work mode
- Load the map only, not every ticket.
- Take the ticket the user named, else the first frontier ticket. Claim it.
- Resolve it, fetching related tickets on demand and consulting the skills the map's Notes name.
- Post the answer as a resolution comment, close the ticket, and append one line to Decisions so far.
- List the follow-on changes the answer implies: fog that graduates into new tickets, anything past the destination ruled out of scope, and tickets the answer invalidates. Show the list and apply only what the user approves; closing or deleting another ticket always needs that approval.
Resolve at most one ticket per session. A batch of research tickets counts as one when the user approves the batch up front. Other sessions edit the tracker concurrently, so re-read before each write.
Done when the ticket is closed, the map shows its gist, and the next frontier is
named. When no tickets and no fog remain, the way is clear: recommend
/prd prepare on the settled decisions.