tracer-wayfinder

Wayfinder

当一个宽泛的想法规模太大，无法在一次 Agent 会话中处理，且推进路径尚不明确时，请使用此流程。Wayfinding 会明确目标，在仓库的问题跟踪器上绘制路线图，并处理其中的决策工单——这些工单要解决的是需要做出决定的问题，而不是可直接执行的构建任务切片——直到路线明确为止。

这是进入 tracer 流程的情境式入口，而非默认入口。如果某项功能的决策能在一次会话内完成，应改用 /tracer-interview-me。

规划，而非执行

Wayfinder 负责规划。它的目标是整理出一套可直接编写规格的决策，每张决策工单最终都要得到一个答案。在开始构建工作前，如果已没有任何待决事项，路线图就算完成。

当你开始想要动手构建时，就说明已经到达目标。将已理清的路线图交给 /tracer-to-spec；切勿将需要多个会话的路线图直接交给 /tracer-implement，否则会跳过整合分散细节的步骤。

通过名称引用

每张路线图和工单都有标题。在叙述内容和目前为止的决策中，引用问题时应使用其链接名称，绝不能只用 ID、编号、路径或 slug。标识符仍会出现在链接中，但不能代替名称。

路线图

路线图是一张标记为 wayfinder:map 的问题，或跟踪器文档中说明的本地等效项。其决策工单是该路线图的子项。

路线图是一个索引，而非存储区。每项决策只保存在一个地方——对应工单的解决记录中；路线图仅保留一行摘要和链接。通过跟踪器的子项／前沿查询发现未关闭的工单，不要将其复制到路线图正文中。

阅读 docs/agents/issue-tracker.md，了解此仓库的 Wayfinding 操作：创建路线图、关联子项、设置阻塞、查询前沿、认领、解决以及更新索引。如果该文件存在但未涵盖这些操作，请先运行 /tracer-setup 更新，再绘制路线图。如果未配置跟踪器，请使用 /tracer-setup 规定的本地 .tracer/ 约定。创建本地状态前，先运行 git check-ignore -q .tracer；如果该目录未被忽略，请将 /.tracer/ 添加到仓库根目录的 .gitignore 中。

路线图正文

## Destination

<One or two lines describing the spec-ready body of decisions this map must produce.>

## Notes

<Domain, skills each session should consult, and standing preferences for this effort.>

## Decisions so far



- [<resolved ticket title>](link) — <one-line gist of the answer>

## Not yet specified



## Out of scope

决策工单

每张决策工单都是路线图的子项，范围应控制在一次全新的 Agent 会话内：

## Question

<The decision or investigation this ticket resolves.>

每张工单都带有一个类型标签：wayfinder:research、wayfinder:prototype、wayfinder:interview 或 wayfinder:task（或本地跟踪器中的等效字段）。

路线图协调者必须在开展任何工作之前，使用已配置跟踪器的分配或状态操作认领工单。指定的工单必须属于此路线图，处于未关闭且未阻塞状态，并且尚未被认领，或已分配给当前工作者；否则应停止。若跟踪器提供原生关联方式，则通过该方式设置阻塞。前沿是路线图下未关闭、未阻塞且未认领的子项。

不要让工作者在查询前沿和认领工单时发生竞争。并行会话开始前，由一名协调者分配不同的工单。将答案记录为解决评论或本地等效内容。资源应链接到工单，绝不可粘贴到路线图中。

工单类型

每个工单都是 HITL——与人类实时协作，由人类代表其立场发言；或者 AFK——完全由 Agent 推进。Agent 绝不会代替人类回答 HITL 工单。

• Research（AFK）：回答需要附有来源的说明、而非简单仓库查找的问题。使用 /tracer-research 启动一个后台工作线程；该工作线程直接开展研究并返回一份带引用的说明。将该说明链接到工单。
• Prototype（HITL）：当问题是某项内容应有何种外观或行为时，创建一个成本低、粗略的产物供人评估。使用全新的 /tracer-prototype 会话，并通过 /tracer-handoff 衔接；在工单中链接临时分支或提交。答案是原型揭示的决策，而不是生产代码。
• Interview（HITL）：默认类型。遵循 /tracer-interview-me 的方法，并将范围限定于这一张工单：每轮询问所有可回答的问题，并提供建议答案；委派事实查找；将决策留给人类。在此工单仍属于某张地图期间，不要执行该技能通常的 /tracer-to-spec 交接。随着术语和持久决策逐渐确定，应用 /tracer-domain-modeling。
• Task（HITL 或 AFK）：做出决策前必须完成的手动工作，例如开通访问权限、注册服务，或移动样本数据以便检查其结构。只有在它能解除决策阻塞时才值得创建，而不是为了交付最终目标。完成后记录所做的工作，以及后续工单所需的结果事实。

认知盲区

地图有意保持不完整。尚未指定用于记录你预见得到、但目前无法精确表述的范围内问题。解决工单会推动边界向外延伸，也可能让这些盲区变得足够明确，从而拆分成新的决策工单。

判断标准是问题是否明确，而不是能否回答：

• 如果现在能精确表述问题，就创建一张工单，即使它受另一张工单阻塞。
• 如果还无法精确表述问题，就保留为盲区。不要预先拆分；一个盲区之后可能变成多个工单，也可能不变成任何工单。

盲区条目一旦拆分成工单，就立即移除，确保问题只存在于一个位置。

范围之外

盲区应朝着目标方向延伸。超出目标范围的工作应归入范围之外，不得放入尚未指定，也不得拆分成工单。

如果发现现有工单实际上超出目标范围，就关闭该工单，不要将其视为路线决策。在范围之外中添加一行说明原因，并链接到该工单。不要将其添加到目前为止的决策中。

会话与并发不变量

每个工单工作线程最多处理一张决策工单。任何时候，每张地图都只能由一名地图协调员负责分配边界和修改地图正文。并行工作的工单工作线程只更新各自分配的子工单，并返回地图增量；协调员按顺序应用这些增量。

制图会话负责创建并连接地图。它可以并行调度多个 AFK 研究工作线程，每个工作线程预先领取一张工单，然后记录它们返回的答案。这是多个工作线程会话之间的并发，而不是让一个工作线程在同一上下文中处理多个问题。

如果某个工作线程消失，其工单仍保持已领取状态。只有在确认该会话已不再活跃后，协调员才能释放或重新分配该工单；如果无法确认，请询问人类。绝不能让两个未领取工单的协调员会话同时处理同一张地图。

调用方式

绘制地图

用户用一个模糊的想法调用 /tracer-wayfinder。

1. 确定目的地。 遵循 tracer 的前沿轮次规则和 /tracer-domain-modeling，围绕目的地开展访谈：在创建工单之前，先确定这张地图要引导用户到达何处。目的地决定范围。
2. 广度优先绘制地图。 继续探索整个空间，而不是深入某一条线索。找出当前可以创建工单的明确决策、它们之间的阻塞关系，以及更远处尚不明确的大致迷雾。与常规的 /tracer-interview-me 不同，遇到可创建工单的问题就停下——本次会话不解决整棵决策树。如果没有发现迷雾，且路线已适合在一次会话中完成，就在创建地图之前停下，并询问是否改用 /tracer-interview-me 继续。
3. 创建地图。 填写 Destination 和 Notes，将 Decisions-so-far 留空，并在 Not yet specified 下勾勒剩余的迷雾。
4. 先创建，再连线。 将当前问题明确的每项决策创建为地图的子工单。第二轮再添加阻塞边，确保所有工单都已有标识。将仍不明确的内容留在 Not yet specified 下。
5. 分派前沿研究。 查询新前沿，并在分派前认领每个无阻塞的研究工单。每个工单启动一个工作线程，使用 /tracer-research，并明确传入低分辨率地图、完整的 Question 和捕获分支；对于需要持久化的分支产物，使用隔离工作树。每个工作线程直接开展研究，在唯一的 research/<map-slug>/<ticket-slug> 分支上撰写一份附有引用的笔记，并返回答案、上下文指针和 ## Map delta，但不要编辑地图。切勿在同一工作树中并发检出多个分支。如果无法使用后台工作线程或隔离环境，就将工单保持为未完成状态，留待新的 AFK 会话处理。
6. 依次记录返回的研究结果。 每个工作线程完成后，协调者在其子工单上发布答案、资源指针和 Map delta，然后关闭工单，再使用与 work-through 步骤 5 相同的索引／迷雾／范围／新工单规则应用该增量。如果使用本地 .tracer/ 地图，由于隔离工作树无法访问 Git 忽略的状态，只允许协调者操作地图或工单文件。如果研究工作超出本次会话，由下一位协调者先记录并应用已完成的结果，再分配新工作。
7. 停止。绘制地图不会回答任何 HITL 工单。

推进地图

用户使用地图 URL、编号或本地路径调用 /tracer-wayfinder。指定工单是可选的。

1. 加载低分辨率地图，了解其 Destination 和 Notes。在协调者模式下，将每个已解决的子工单与 Decisions so far 和 Out of scope 进行比较；如有遗漏，分配工作前先补齐。
2. 验证并选择一个工单。 用户指定的工单必须属于此地图，且处于开放、未阻塞、未认领状态，除非协调者已将其分配给此工作者。否则停止并说明原因。未指定工单时，协调者选择最前沿的工单，并在深入阅读或讨论前认领。
3. 解决工单。 仅在需要时深入查看相关工单和资源。遵循 Notes 中指定的技能。默认采用上述针对工单的访谈和领域建模规范。
4. 记录子工单的解决结果。 给出答案，并提供 ## Map delta，准确说明由此产生的索引、迷雾、范围和新工单变更。在共享跟踪器上，工作者同时发布两者并关闭子工单。对于本地 .tracer/ 地图，工作者返回两者，由协调者在协调用的检出目录中记录。并行工单工作者到此为止；不得编辑地图正文。
5. 以协调者身份推进地图。 一次应用一个已完成的增量。将每条关联的 gist 追加到 Decisions so far，先创建再关联新确定的工单，清除已消除的迷雾，将超出目标范围的工作移至 Out of scope，并更新已失效的工单或将其划入范围外，确保每个已关闭的子工单都有记录。工单工作者不得替换地图正文。
6. 检查是否完成。 重新查询每个子工单，并确认每个已解决的子工单都出现在 Decisions so far 或 Out of scope 中。仅当没有开放、已认领或进行中的决策工单，没有未编入索引的已解决子工单，且 Not yet specified 为空时，地图才算清晰。然后使用以下内容移交：Invoke /tracer-to-spec with the cleared map <URL-or-path>.

每张地图只运行一个协调者会话。若要并行处理前沿工单，协调者应先认领不同工单，再启动或移交给指定的工作者会话，最后依次应用它们返回的增量。