Back to Details

wayfinder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
一个松散想法出现了：它太大，单个 agent session 装不下，而且前路仍在 fog 中。这个 skill 会把它绘制成 repo issue tracker 上的 shared map，然后一次处理一个 ticket。Map 与领域无关：工程工作、课程内容，或任何符合这个形状的事项都可以。
A loose idea emerges: it's too big to fit into a single agent session, and the path ahead is still in the fog. This skill will map it into a shared map on the repo issue tracker, then handle one ticket at a time. The Map is domain-agnostic: it works for engineering work, course content, or anything that fits this shape.

Refer by name

Refer by name

每张 map 和每个 ticket 都是 issue，因此都有一个 name：它的 title。在所有给人看的内容里，包括叙述和 map 的 Decisions-so-far，都用 name 引用它，不要只写裸 id、number 或 slug。一堵 
#42, #43, #44
很难读；name 一眼就能看懂。Id 和 URL 不会消失，它们被包在 name 的 link 里面，但不单独替代 name。
Each map and each ticket is an issue, so it has a name: its title. In all human-facing content, including narratives and the map's Decisions-so-far, refer to it by name, not just by bare id, number, or slug. A wall of 
#42, #43, #44
is hard to read; a name is instantly understandable. Ids and URLs don't disappear—they're wrapped in the name's link—but don't replace the name alone.

The Map

The Map

Map 是这个 repo issue tracker 上一个带 
wayfinder:map
label 的单独 issue，是 canonical artifact。它的 tickets 是 map 的 child issues。
Map 是 index，不是 store。它列出已经做出的 decisions，并指向保存细节的 tickets；一个 decision 只存在一个地方，也就是它的 ticket。因此 map 不复述细节，只给 gist 和 link。
Map、child tickets、blocking 和 frontier queries 的物理表达方式取决于 tracker。 查阅 
docs/agents/issue-tracker.md
的 "Wayfinding operations" section，了解这个 repo 如何表达它们。如果没有该 doc，默认使用 local-markdown tracker。
The Map is a single issue on this repo's issue tracker with the 
wayfinder:map
label, serving as the canonical artifact. Its tickets are child issues of the map.
The Map is an index, not a store. It lists decisions that have been made and points to the tickets where details are saved; a decision exists in only one place, which is its ticket. Therefore, the Map doesn't repeat details, only provides a gist and a link.
The physical expression of Map, child tickets, blocking, and frontier queries depends on the tracker. Consult the "Wayfinding operations" section of 
docs/agents/issue-tracker.md
to learn how this repo expresses them. If that doc doesn't exist, use the local-markdown tracker by default.

The map body

The map body

Map 是低分辨率的全局视图，每个 session 加载一次。Open tickets 不列在里面；它们是 open child issues，通过 query 找到。
markdown
undefined
The Map is a low-resolution global view, loaded once per session. Open tickets are not listed in it; they are open child issues found via query.
markdown
undefined

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>

Fog

Fog

<!-- see "Fog of war" for what belongs here --> 
undefined
<!-- see "Fog of war" for what belongs here --> 
undefined

Tickets

Tickets

每个 ticket 都是 map 的 child issue；tracker 的 issue id 是它的 identity。Body 是一个问题，大小控制在一个 100K token agent session 内：
markdown
undefined
Each ticket is a child issue of the map; the tracker's issue id is its identity. The body is a question, sized to fit within a 100K token agent session:
markdown
undefined

Question

Question

<the decision or investigation this ticket resolves> ```
每个 ticket 带一个 
wayfinder:<type>
label，取值为 
research
、
prototype
、
grilling
、
task
（见 Ticket Types）。
Session claim ticket 的方式，是在任何工作开始前先把 ticket assign 给 driving map 的 dev。这个 assignee 就是 claim：open 且 unassigned 的 ticket 才是 unclaimed。
Blocking 使用 tracker 的 native dependency relationship；这很重要，因为 tracker UI 会可视化 frontier，人类不用打开 map 也能看到哪些 ticket 可拿。只有 tracker 没有 native blocking 时，才退回 body convention。一个 ticket 的所有 blockers 都关闭后，它就是 unblocked；frontier 是 open、unblocked、unclaimed 的 children，也就是已知世界的边缘。
答案不写进 body，而是在 resolution 时记录（见 Work through the map）。解决 ticket 时产生的 assets 从 issue 链接出去，不粘贴进 body。
<the decision or investigation this ticket resolves> ```
Each ticket has a 
wayfinder:<type>
label, with values including 
research
, 
prototype
, 
grilling
, 
task
(see Ticket Types).
A session claims a ticket by assigning it to the dev driving the map before any work begins. This assignee is the claim: only open and unassigned tickets are unclaimed.
Blocking uses the tracker's native dependency relationship; this is important because the tracker UI visualizes the frontier, allowing humans to see which tickets are available without opening the map. Only if the tracker has no native blocking feature should we fall back to body conventions. A ticket becomes unblocked once all its blockers are closed; the frontier refers to open, unblocked, unclaimed child issues—the edge of the known world.
Answers are not written into the body, but recorded upon resolution (see Work through the map). Assets generated when resolving a ticket are linked from the issue, not pasted into the body.

Ticket Types

Ticket Types

  • Research：阅读 documentation、third-party APIs，或 knowledge bases 等 local resources。创建 markdown summary 作为 linked asset。当需要当前 working directory 外的知识时使用。
  • Prototype：通过 cheap、rough、concrete artifact 提高讨论 fidelity，例如 outline、rough take、stub，或通过 /prototype skill 写 UI/logic code。Prototype 作为 asset 链接。当核心问题是 "how should it look" 或 "how should it behave" 时使用。
  • Grilling：与 agent 对话。使用 /grilling 和 /domain-modeling skills。一次问一个问题。默认类型。
  • Task：讨论推进前必须完成的 literal manual work；没有要决定、prototype 或 research 的内容。例如搬数据、注册服务、配置访问权限。Agent 能自动化就自动化，否则给人类精确 checklist。完成后即 resolved；答案记录做了什么，以及后续 tickets 依赖的事实（credentials location、new URLs、row counts 等）。
  • Research: Read documentation, third-party APIs, or local resources like knowledge bases. Create a markdown summary as a linked asset. Use this when knowledge outside the current working directory is needed.
  • Prototype: Increase discussion fidelity through cheap, rough, concrete artifacts, such as outlines, rough drafts, stubs, or writing UI/logic code via the /prototype skill. The prototype is linked as an asset. Use this when the core question is "how should it look" or "how should it behave".
  • Grilling: Converse with an agent. Use the /grilling and /domain-modeling skills. Ask one question at a time. This is the default type.
  • Task: Literal manual work that must be completed before discussion can proceed; there is nothing to decide, prototype, or research. Examples include moving data, registering services, configuring access permissions. The agent automates it if possible; otherwise, provides a precise checklist for humans. Resolve it once completed; record what was done and facts that subsequent tickets depend on (credentials location, new URLs, row counts, etc.).

Fog of war

Fog of war

Map 是 有意 不完整的：不要描绘你还看不见的东西。Tickets 之外是 fog：那些你能感觉到以后会来的 decisions 和 investigations，但它们悬在仍未解决的问题之上，暂时还无法钉住。解决一个 ticket 会清掉它前方的一片 fog，把现在已经能说明的问题升级成新的 tickets；一次一个，直到通向目标的路清楚且没有 tickets 剩下。
Map 的 Fog section 用来记录这种朦胧视野：怀疑中的问题、之后要回访的区域、暂时推迟的风险。可以按视野允许的粗细来写；它也是协作者阅读这个 effort 走向时的路标。
Fog or ticket? 测试标准是你现在能不能把问题说清楚，而不是现在能不能回答它。
  • Ticket when 问题已经清晰，即使它被 blocked、现在不能处理。
  • Fog when 你还不能把它说得那么清楚。不要把 fog 预先切成 ticket-sized pieces：fog 比 ticket 粗，frontier 到达后，一片 fog 可能升级成多个 tickets，也可能一个都没有。
Fog 只排除已经决定的内容（Decisions so far）和已经是 ticket 的内容。
The Map is intentionally incomplete: don't depict what you can't yet see. Beyond tickets lies the fog: decisions and investigations you sense will come later, but they hang over unresolved questions and can't be pinned down for now. Resolving a ticket clears a patch of fog ahead, elevating questions that can now be defined into new tickets; do this one at a time until the path to the goal is clear and no tickets remain.
The Fog section of the Map is used to record this hazy vision: suspected questions, areas to revisit later, risks that are temporarily postponed. It can be written at whatever granularity your vision allows; it also serves as a signpost for collaborators to understand the direction of this effort.
Fog or ticket? The test is whether you can clearly state the question now, not whether you can answer it now.
  • Ticket when the question is clear, even if it's blocked and can't be addressed now.
  • Fog when you can't state it that clearly yet. Don't pre-cut fog into ticket-sized pieces: fog is coarser than tickets, and when the frontier reaches it, a patch of fog may elevate into multiple tickets, or none at all.
Fog excludes only content that has already been decided (Decisions so far) and content that is already a ticket.

Invocation

Invocation

两种模式。无论哪种，每个 session 绝不要 resolve 超过一个 ticket。
Two modes. Regardless of which mode, never resolve more than one ticket per session.

Chart the map

Chart the map

用户带着松散想法调用。
  1. 运行 
    /grilling
    和 
    /domain-modeling
    session，浮现 open decisions。
  2. Create the map（label 
    wayfinder:map
    ）：填好 Notes，Decisions-so-far 为空，Fog 初步勾勒。
  3. Create the tickets you can specify now 作为 map 的 child issues，然后第二遍再 wire blocking edges（issues 需要 ids 后才能互相引用）。Wiring 会把它们分成 frontier 和 blocked；现在还说不清的都留在 Fog。
  4. 停止。Charting the map 是一个 session 的工作；不要同时 resolve tickets。
The user invokes with a loose idea.
  1. Run 
    /grilling
    and 
    /domain-modeling
    sessions to surface open decisions.
  2. Create the map (label 
    wayfinder:map
    ): fill in Notes, leave Decisions-so-far empty, and outline the initial Fog.
  3. Create the tickets you can specify now as child issues of the map, then wire the blocking edges in a second pass (issues need ids before they can reference each other). Wiring will divide them into frontier and blocked tickets; leave anything you can't yet define clearly in Fog.
  4. Stop. Charting the map is one session's work; do not resolve tickets at the same time.

Work through the map

Work through the map

用户用 map（URL 或 number）调用。Ticket 是 optional；没有 ticket 时，你选择下一个 decision，而不是用户选择。
  1. 加载 map：低分辨率视图，而不是每个 ticket body。
  2. 选择 ticket。用户点名就用它；否则按顺序拿第一个 frontier ticket。Claim it：任何工作开始前先 assign 给自己。
  3. Resolve it：按需 zoom，只在需要时获取相关或已关闭 ticket 的完整 body；调用 
    ## Notes
    block 提到的 skills。不确定时用 
    /grilling
    和 
    /domain-modeling
    。
  4. 记录 resolution：把答案作为 resolution comment 发布，close issue，并向 map 的 Decisions-so-far 追加 context pointer。
  5. 添加新浮现的 tickets（create-then-wire）；把答案已经澄清的 fog 升级，并从 Fog 中清掉每个已升级 patch，让它只作为新 ticket 存在。如果这个 decision 使 map 其他部分失效，更新或删除那些 tickets。
用户可能并行运行 unblocked tickets，所以要预期其他 sessions 同时编辑 tracker。
The user invokes with a map (URL or number). A ticket is optional; if no ticket is provided, you choose the next decision instead of the user.
  1. Load the map: use the low-resolution view, not the full body of each ticket.
  2. Select a ticket. Use the one the user names; otherwise, take the first frontier ticket in order. Claim it: assign it to yourself before any work begins.
  3. Resolve it: zoom as needed, only fetching the full body of relevant or closed tickets when required; invoke the skills mentioned in the 
    ## Notes
    block. Use 
    /grilling
    and 
    /domain-modeling
    if unsure.
  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 emerged tickets (create-then-wire); elevate fog that has been clarified by the answer, and clear each elevated patch from the Fog so it exists only as a new ticket. If this decision invalidates other parts of the map, update or delete those tickets.
Users may run unblocked tickets in parallel, so expect other sessions to edit the tracker simultaneously.