SuperAPI AI Directory

wayfinder

General & other

View repository

Updated 10-16 08:42

About this skill

Wayfinder

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 prepare on the settled decisions

Creates/Modifies:

  • GitHub issues: the map (label wayfinder:map), child tickets (label wayfinder:<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-me and domain-modeling skills for grilling tickets and for naming the destination
  • Run the research skill for research tickets
  • Run the prototype skill for prototype tickets
  • Recommend prd-dispatch to turn the finished map into a feature issue
  • Recommend show-me-your-work for 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

  1. Name the destination. Run grill-me and domain-modeling until the destination is one or two lines. It fixes the scope.
  2. 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.
  3. 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).
  4. Start each new research ticket's resolution in a parallel subagent.

Done when the map and its first tickets exist and nothing was resolved by hand.

Work mode

  1. Load the map only, not every ticket.
  2. Take the ticket the user named, else the first frontier ticket. Claim it.
  3. Resolve it, fetching related tickets on demand and consulting the skills the map's Notes name.
  4. Post the answer as a resolution comment, close the ticket, and append one line to Decisions so far.
  5. 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.