Back to Details

wayfinder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the destination isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a shared map on the repo's issue tracker, then works its decision tickets — questions whose resolution is a decision, not slices of a build to execute — one at a time until the route is clear.
The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
你有了一个模糊的想法——它超出了单个Agent会话的处理范围，且充满不确定性：从当前状态到目标的路径尚不清晰。路径探索（Wayfinding）的核心是找到这条路径，而非直接冲向目标。本Skill将路径规划为代码库问题追踪器上的共享地图，然后逐个处理决策工单——这些工单对应的是需要做出决策的问题，而非可执行的构建任务切片——直到路径完全清晰。
目标会因任务不同而变化，明确目标是路径规划的第一步——它将影响每一个工单。目标可能是一份可交付并迭代的规范、一项需在规划开始前确定的决策，或是像数据结构迁移这类直接落地的变更。该地图与领域无关——无论是工程工作、课程内容，只要符合这种模式都适用。

Plan, don't do

只规划，不执行

Wayfinder is planning by default: each ticket resolves a decision, and the map is done when the way is clear — nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off. An effort can override this in its Notes — carrying execution into the map itself — but absent that, produce decisions, not deliverables.
Wayfinder默认是规划工具：每个工单解决一项决策，当路径清晰时，地图即完成——此时无需再做任何决策，即可着手执行任务。当你产生直接动手干活的冲动时，通常意味着你已抵达地图的边界，是时候交接任务了。任务可通过其Notes部分覆盖这一默认规则——将执行环节纳入地图本身——但若无特殊说明，应产出决策，而非可交付成果。

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.
每张地图和每个工单都是一个issue，因此都有一个名称——即其标题。在人类阅读的所有内容中——叙述文本、地图的“已做出决策”部分——都应使用名称引用，绝不能仅使用ID、编号或短链接。一串
#42, #43, #44
难以辨认，而名称一目了然。ID和URL不会消失——名称会包裹对应的链接——但它们应隐藏在名称背后，而非直接替代名称。

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.
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. The issue tracker should have been provided to you — run 
$setup-matt-pocock-skills
if not. Consult the tracker doc's "Wayfinding operations" section for how this repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
地图是代码库问题追踪器上的单个issue，标记为
wayfinder:map
——这是标准工件。其工单是地图的子issue。
地图是一个索引，而非存储库。它列出已做出的决策，并指向承载决策细节的工单；每项决策仅存在于一个位置——对应的工单——因此地图绝不会重复决策内容，仅提供摘要并链接至工单。
地图、其子工单、阻塞关系和前沿查询的实际存储位置取决于追踪器类型。 应已为你提供问题追踪器——若未提供，请运行
$setup-matt-pocock-skills
。查阅追踪器文档的“路径探索操作”部分，了解此代码库如何实现这些功能。若未提供任何追踪器，默认使用本地Markdown追踪器。

The map body

地图主体

The whole map at low resolution, loaded once per session. Open tickets are not listed — they are open child issues, found by query.
markdown
undefined
低分辨率的完整地图，每个会话加载一次。开放工单不会被列出——它们是开放的子issue，可通过查询找到。
markdown
undefined

Destination

Destination

<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

Notes

Notes

<domain; skills every session should consult; standing preferences for this effort>
<domain; skills every session should consult; standing preferences for this effort>

Decisions so far

Decisions so far

<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->
  • <closed ticket title> — <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> — <one-line gist of the answer>

Not yet specified

Not yet specified

<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->

Out of scope

Out of scope

<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates --> 
undefined
<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates --> 
undefined

Tickets

工单

Each ticket is a child issue of the map; the tracker's issue id is its identity. Its body is the question, sized to one 100K token agent session:
markdown
undefined
每个工单都是地图的子issue；追踪器的issue ID是其唯一标识。工单主体是一个问题，大小控制在单个10万Token的Agent会话范围内：
markdown
undefined

Question

Question

<the decision or investigation this ticket resolves> ```
Each ticket carries a 
wayfinder:<type>
label — one of 
research
, 
prototype
, 
grilling
, 
task
(see Ticket Types).
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.
Blocking uses the tracker's native dependency relationship — essential because it renders the frontier visually in the tracker's own UI, so the human sees what's takeable without opening the map. Only a tracker that lacks native blocking falls back to a body convention. A ticket is unblocked when every ticket blocking it is closed; the frontier is the open, unblocked, unclaimed children — the edge of the known.
The answer isn't part of the body — it's recorded on resolution (see Work through the map). Assets created while resolving a ticket are linked from the issue, not pasted in.
<the decision or investigation this ticket resolves> ```
每个工单都带有
wayfinder:<type>
标签——类型包括
research
、
prototype
、
grilling
、
task
（详见工单类型）。
会话在开始任何工作前，需先认领工单：将其分配给驱动地图开发的开发者，这样并发会话就会跳过该工单。工单的经办人即为认领标识：未分配的开放工单项为未认领状态。
阻塞关系使用追踪器的原生依赖关系——这一点至关重要，因为它能在追踪器自身UI中可视化展示前沿工单，让人类无需打开地图就能看到可处理的任务。只有当追踪器不支持原生阻塞功能时，才会退而采用主体约定。当所有阻塞该工单的工单都已关闭时，该工单即为未阻塞状态；前沿工单是指开放、未阻塞且未被认领的子工单——代表已知范围的边界。
答案不属于工单主体——它会在工单解决时被记录（详见遍历地图）。解决工单过程中创建的资产会从issue链接，而非粘贴到其中。

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).
  • Research (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a 
    $research
    subagent. 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.
每个工单要么是HITL——人机协作，需与能自主表达的人类共同处理——要么是AFK——仅由Agent驱动。HITL工单只能通过实时交互解决；Agent绝不能替代人类参与交互（若一个grilling Agent自行回答问题，则违反了此规则）。
  • Research（AFK）：阅读文档、第三方API或知识库等本地资源，找出决策所需的事实。由
    $research
    子Agent解决。当需要当前工作目录之外的知识时使用。
  • Prototype（HITL）：通过制作低成本、粗糙的具体工件来提升讨论的保真度——比如大纲、草稿、存根，或通过$prototype Skill生成的UI/逻辑代码。将原型作为资产链接。当核心问题是“它应该是什么样子”或“它应该如何表现”时使用。
  • Grilling（HITL）：通过$grilling和$domain-modeling Skills进行一对一的对话。这是默认类型。
  • Task（HITL或AFK）：在做出决策前必须完成的手动工作——无需决策、原型制作或研究，但讨论会因该工作未完成而受阻。例如注册服务以评估其API、配置访问权限、迁移数据以查看其结构。这是唯一一种“执行”而非“决策”的工单类型——它的存在意义是为决策扫清障碍，而非直接交付目标。Agent可独立完成的部分（AFK）自行驱动；否则向人类提供精确的检查清单（HITL）。工作完成后工单即解决；答案需记录已完成的工作以及后续工单依赖的事实（如凭证位置、新URL、行数统计）。

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.
The map's Not yet specified section is where that dim view is written down: the suspected question, the area to revisit later. It's the undiscovered frontier toward the destination — everything here is in scope, just not sharp enough to ticket. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
Fog or ticket? The test is whether you can state the question precisely now — not whether you can answer it now.
  • Ticket when the question is already sharp — even if it's blocked and you can't act on it yet.
  • Not yet specified when you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
Not yet specified excludes what's already decided (Decisions so far), what's already a live ticket, and what's out of scope (the next section).
地图是故意不完整的：不要规划你尚未看清的内容。现有工单之外是战争迷雾——你能意识到即将到来的决策和调查，但因依赖未解决的问题而无法明确界定。解决工单会扫清其前方的迷雾，将现在可明确的内容转化为新工单——逐个处理，直到通往目标的路径清晰且无剩余工单。
地图的“尚未明确”部分用于记录这种模糊的预期：疑似存在的问题、后续需 revisit 的领域。这是朝向目标的未探索边界——此处的所有内容都在范围内，只是尚未清晰到可创建工单的程度。可根据模糊程度自由记录；它同时也能作为路标，让协作者了解任务的前进方向。
迷雾还是工单？ 判断标准是你现在能否准确表述问题——而非你现在能否回答它。
  • 创建工单：当问题已经明确时——即使它当前被阻塞无法处理。
  • 归入尚未明确：当你还无法准确表述问题时。不要预先将迷雾切割成工单大小的片段：迷雾比工单更粗糙，一片迷雾可能在边界推进后转化为多个工单，也可能一个都不会产生。
“尚未明确”部分不包含已决策内容（已做出决策）、已创建的现有工单，以及超出范围的内容（下一部分）。

Out of scope

超出范围

Fog only ever gathers toward the destination. The destination fixes the scope, so work beyond it is out of scope — it isn't fog, and it doesn't belong in Not yet specified. It gets its own Out of scope section on the map: work you've consciously ruled out of this effort. Scope, not sharpness, lands it here.
Out-of-scope work never graduates — the frontier stops at the destination — so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — close it (a closed ticket is unambiguously off the frontier) and leave one line in the Out of scope section: the gist plus why it's out of scope, linking the closed ticket. It stays out of Decisions so far, which records the route actually walked — a scope boundary isn't a step on it.
迷雾只会在朝向目标的方向聚集。目标定义了范围，因此超出目标的工作属于超出范围——这不是迷雾，不应归入“尚未明确”部分。它会在地图上拥有独立的“超出范围”部分：你已明确排除在本次任务之外的工作。决定它归属的是范围，而非清晰度。
超出范围的工作永远不会被纳入——边界止于目标——因此只有当目标被重新定义时，才会被重新考虑，且会作为全新任务，而非继续原任务。
将某项工作排除在范围之外是一种范围界定行为，而非路径上的步骤。当已存在的工单被发现超出目标范围——规划时误纳入，或因决策暴露——应关闭该工单（关闭的工单明确不属于前沿），并在“超出范围”部分留下一行记录：摘要及排除原因，链接至已关闭的工单。该工单不会被纳入“已做出决策”部分，因为该部分记录的是实际走过的路径——范围边界并非路径上的一步。

Invocation

调用方式

Two modes. Either way, never resolve more than one ticket per session — with the exception of research tickets.
两种模式。无论哪种模式，每个会话最多解决一个工单——研究工单除外。

Chart the map

绘制地图

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.
  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. Fire the research subagents. For each 
    research
    ticket you just created, spin up a 
    $research
    subagent to resolve it in parallel, capturing its findings on a throwaway 
    research/<name>
    branch with a context pointer from the ticket.
  6. Stop — charting is one session's work; it hand-resolves nothing.
用户通过模糊想法调用。
  1. 明确目标。运行
    $grilling
    和
    $domain-modeling
    会话，确定此地图要抵达的目标——规范、决策或变更。目标定义了范围，因此需首先确定。
  2. 绘制边界。再次进行grilling，此次采用广度优先：覆盖整个领域而非深入单个线程，找出未解决的决策和当前可采取的第一步。如果未发现迷雾——通往目标的路径已清晰，整个任务小到可在单个会话内完成——则无需地图。停止操作并询问用户希望如何继续。
  3. 创建地图（标记
    wayfinder:map
    ）：填写目标和Notes部分，“已做出决策”部分为空，将迷雾内容写入“尚未明确”部分。
  4. 创建当前可明确的工单作为地图的子issue——然后在第二轮操作中设置阻塞关系（issue需要ID才能相互引用）。设置阻塞关系后，工单会被分为前沿工单和阻塞工单；所有尚未明确的内容仍保留在迷雾中——即“尚未明确”部分。
  5. 启动研究子Agent。针对每个刚创建的
    research
    工单，启动一个
    $research
    子Agent并行解决，将研究结果存储在临时的
    research/<name>
    分支中，并在工单中添加上下文指针。
  6. 停止操作——绘制地图是一个会话的工作；不会手动解决任何工单。

Work through the map

遍历地图

User invokes with a map (URL or number). A ticket is optional — without one, you pick the next decision, not the user.
  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
    .
  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.
The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.
用户通过地图（URL或编号）调用。工单为可选参数——若未指定，由你选择下一个决策，而非用户指定。
  1. 加载地图——低分辨率视图，无需加载所有工单主体。
  2. 选择工单。若用户指定了工单，则使用该工单。否则按顺序选择第一个前沿工单。认领工单：在开始任何工作前将其分配给自己。
  3. 解决工单——按需放大：根据需要获取相关或已关闭工单的完整主体；调用
    ## Notes
    块中指定的Skills。若有疑问，使用
    $grilling
    和
    $domain-modeling
    。
  4. 记录解决方案：将答案作为解决评论发布，关闭该issue，并在地图的“已做出决策”部分添加上下文指针。
  5. 添加新出现的工单（先创建再设置阻塞关系）；将答案已明确的迷雾内容转化为新工单，并从“尚未明确”部分移除这些内容，使其仅存在于新工单中。若答案显示某个工单——当前工单或其他工单——超出目标范围，应将其排除在范围之外，而非在路径上解决它。若决策使地图的其他部分失效，更新或删除这些工单。
用户可并行处理未阻塞工单，因此需考虑其他会话同时编辑追踪器的情况。