SuperAPI AI Directory

wayfinder

General & other

View repository

Updated 10-16 09:55

About this skill

Wayfinder

An item is too large to fit in a single Agent session, and the route from the current state to thedestinationis still shrouded in fog. Wayfinder does not charge straight at the destination; instead, it establishes a sharedmapin the repository, records the questions that can currently be stated clearly asdecision tickets, and resolves them one by one, advancing the frontier until the route is clear.

The destination can be a complete decision ready to enter to-prd , a key choice that must be locked before implementation, or a migration whose path needs to be determined across multiple rounds. The first step is always to name the destination, because it determines whether each ticket belongs to the current map.

Plan only, do not implement

Wayfinder by default only resolves decisions. Each ticket produces an answer, not a final feature; when a question has become clear construction work, it has crossed the edge of the map and should be handed to to-prd、to-api、to-task or impl. Only when the map's Notes explicitly requires planning and execution side by side should implementation be brought into the map.

Map and decision tickets

Use the local Markdown layout already present in the current repository:

docs/scratch/<NN>-<中文需求名称>/
├── WAYFINDER.md
└── wayfinder/
    ├── 01-<中文问题名称>.md
    └── 02-<中文问题名称>.md

Reuse the existing requirements directory; if there is no corresponding directory, create it as the current maximum number in docs/scratch/ plus one. Use the unified terminology from the project CONTEXT for the names of the map and tickets.

Map

WAYFINDER.md is the sole authoritative map: it is an index, not a repository of answers. The complete answer for each decision exists only in the corresponding decision ticket; the map keeps only a one-sentence summary and a relative link.

# <地图名称>

## Destination

<到达地图终点时得到什么;一至两行>

## Notes

<领域、每轮必须加载的项目知识、是否允许执行、长期偏好>

## Decisions so far

- [<已关闭决策票名称>](./wayfinder/01-xxx.md):<答案的一句话摘要>

## Not yet specified

<确定仍在范围内、但目前还无法精确表述为问题的迷雾>

## Out of scope

<已明确越过目的地的事项及原因>

Decision ticket

Each ticket resolves only one question that can be closed within a single session:

# <问题名称>

- Type: research | prototype | grilling | task
- Status: open | claimed | resolved
- Blocked by: <相对链接列表;无依赖时写 none>

## Question

<本票要回答的精确问题>

## Resolution

<解决时追加答案;未解决时留空>

The file number is a stable ordering and does not replace the name. When referring to a decision ticket to users or from the map, always use the full linked name, not the bare number.

Blocked by All tickets in resolved arefrontier, this ticket is unblocked. The open, unblocked tickets sorted by file number. Before starting work, first change the selected ticket to claimed; when finished, write the Resolution and change it to resolved。

Ticket types

Each ticket either requires human involvement (HITL) or can be completed independently by the Agent (AFK):

  • research(AFK): Read code, project knowledge, official documentation, or external materials to fill in the facts that a decision depends on. Conclusions must be accompanied by reviewable file locations or sources.
  • prototype(HITL): Create a cheap, rough, reactable prototype to answer "what should it look like" or "is the behavior appropriate." Link the prototype path to the Resolution, and resolve this ticket only after user feedback.
  • grilling(HITL): Use ask-me to complete a decision tree around this ticket's question. The Agent does not answer on the user's behalf decisions that the user must make.
  • task (HITL or AFK): Manual matters that must be completed before a decision but have no decision content themselves, such as obtaining access permissions or migrating a sample dataset. It only unblocks decisions; it does not deliver the destination.

Fog and scope

The map is intentionally incomplete. Questions that can currently be stated precisely are established as decision tickets; content where only a direction is visible and the question cannot yet be stated precisely remains in Not yet specified. The criterion is "can the question be stated accurately now," not "can it be answered now."

After resolving a ticket, re-examine the fog: the parts that can now be stated precisely graduate into new tickets and are removed from Not yet specified , so that it retains only a single authoritative location.

Write matters beyond the destination into Out of scope, and they will not reappear as the frontier advances. If an existing ticket is proven to be out of scope, close that ticket, explain the reason in Resolution, and leave only a one-sentence summary with a link in Out of scope ; do not record it in Decisions so far。

How to invoke

Both modes follow the same limit: a session resolves at most one non-research decision ticket.

Build the map

The user invokes it with a large matter that still has fog:

  1. Name the destination: the result the closure map is ultimately meant to achieve; use it to define the scope.
  2. Breadth-first scan: horizontally discover the decisions that can already be asked precisely, their dependencies, and the fog that still cannot be asked about, without going deep into resolving any ticket. If the route is already completely clear and a single session is enough to contain it, stop building the map and explain that you can proceed directly to the corresponding workflow.
  3. Create the map: write Destination, Notes, Not yet specified, and Out of scope, keeping Decisions so far empty.
  4. Create the currently describable tickets: create all files first, then write Blocked by, yielding a workable frontier.
  5. Stop: a map-building session does not conveniently resolve grilling, prototype, or task tickets.

Advance the map

The user invokes it again with the WAYFINDER.md path; they may specify a ticket, or let the Agent choose:

  1. Load only the low-resolution view of the map, not all tickets at once.
  2. When the user specifies a ticket, first confirm that it is unblocked; when none is specified, choose the first ticket in the frontier. First change it to claimed。
  3. Read this ticket, relevant project knowledge, and closed tickets that genuinely affect the answer, and resolve the matter according to the ticket type.
  4. Write the complete answer into Resolution, change it to resolved; in the map Decisions so far append a one-sentence summary and a relative link.
  5. Add or adjust decision tickets, dependencies, and fog based on the answer; move content proven to be out of bounds into Out of scope.
  6. If the frontier is empty but fog remains, explicitly record the current blocking facts; if both the frontier and the fog are empty, the map is complete, and hand it over as actually needed to to-prd、to-api、to-task or impl。

When advancing different decision tickets concurrently, each execution context must first claim a different frontier ticket and modify only its own ticket; map index updates must be merged based on the latest files and must not overwrite decisions newly written by other sessions.