wayfinder

一个模糊的想法出现了，它太大，无法在一次 Agent 会话中完成，而且笼罩在迷雾中：通往目标的路尚不可见。Wayfinding 要做的是找到这条路，而不是径直冲向目标。这项技能会在仓库的 issue 跟踪器上绘制一张共享地图，然后逐个处理地图上的决策工单（其解决结果是一个决策，而不是等待执行的构建任务切片），直到路线清晰。

每项工作的目标各不相同，为目标命名是绘制地图的第一步：它会影响每张工单。目标可能是一份待交接并迭代完善的规格说明、一项需要在开始规划前敲定的决策，也可能是一项就地完成的变更，例如数据结构迁移。这张地图与领域无关：无论是工程工作、课程内容，还是其他符合这种形式的内容，都适用。

规划，而非执行

Wayfinder 默认用于规划：每张工单都要解决一个决策；当路线清晰、在有人着手执行之前已无待决事项时，地图便绘制完成。想直接开始执行工作的冲动，通常意味着你已经到达地图的边缘，该交接了。某项工作可以在其备注中覆盖这一默认设置，将执行工作也纳入地图；但除非有此说明，否则产出决策，而不是交付成果。

按名称引用

每张地图和每张工单都是一个 issue，因此都有一个名称：它的标题。在所有人类会阅读的内容中（叙述、地图中的“目前已做出的决策”），都要用名称来引用它，绝不要只用 ID、数字或 slug。一长串 #42, #43, #44 难以辨认；名称则一目了然。ID 和 URL 并未消失；名称会包裹其链接，但它们必须_包含在_名称中，不能取代名称。

地图

地图是本仓库 issue 跟踪器上的一个独立 issue，标记为 wayfinder:map，也是规范的产物。地图上的工单是地图的子 issue。

地图是一个索引，而不是存储区。它列出已做出的决策，并指向包含详细信息的工单；每项决策只存在于一个地方，即其工单，因此地图不会重述决策，只会概述并附上链接。

地图、其子工单、阻塞关系和前沿查询的实际存放位置由跟踪器决定。 应已为你提供 issue 跟踪器。如果没有，请告诉用户运行 /setup-agent-skills。查阅跟踪器文档的“Wayfinding 操作”部分，了解_此_仓库如何表示这些内容。如果没有提供跟踪器，则默认使用本地 Markdown 跟踪器。

地图正文

每次会话加载一次完整的低分辨率地图。未结工单不会列出：它们是通过查询找到的未结子 issue。

## 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.>

## Notes

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

## Decisions so far



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

## Not yet specified



## Out of scope

工单

每张工单都是地图的一个子 issue；跟踪器的 issue ID 就是它的身份。其正文是一个问题，规模适合在一次 100K token 的 Agent 会话中解决：

## Question

<the decision or investigation this ticket resolves>

每张工单都带有一个 wayfinder:<type> 标签，类型可以是 research、prototype、grilling、task 中的一种（参见工单类型）。

会话会通过先将工单分配给负责推进地图的开发者来认领工单，必须在任何工作开始前完成，这样并行会话就会跳过该工单。该受派人_就是_认领者：未结且未分配的工单就是未认领工单。

阻塞关系使用跟踪器的原生依赖关系：这至关重要，因为它能在跟踪器自己的 UI 中_直观_呈现前沿，让人不用打开地图就能看到哪些工单可以着手处理。只有不支持原生阻塞关系的跟踪器，才会退回到正文约定。若阻塞某张工单的所有工单都已关闭，则该工单为未阻塞；前沿是未结、未阻塞且未认领的子工单，也就是已知范围的边界。

答案不属于正文；它会在工单解决时记录（参见推进地图）。解决工单时创建的资源应链接到 issue，而不是直接粘贴进去。

工单类型

每个工单要么是 HITL（human in the loop，与人类一起完成，由人类本人发表意见），要么是 AFK，完全由 Agent 独自推进。HITL 工单只能通过这种实时交流来解决；Agent 不能代替人类一方发言（一个自己回答自己问题的 grilling Agent 就违反了这一点）。

• Research（AFK）：阅读文档、第三方 API 或知识库等本地资源，以找出某个决策所依赖的事实。由子代理调用 Skill tool 并传入 "research" 来完成。当需要当前工作目录之外的知识时使用。
• Prototype（HITL）：通过制作一个低成本、粗略但具体的产出物（大纲、粗略方案、桩代码，或 UI/逻辑代码）来提高讨论的保真度，供各方评审。调用 Skill tool 并传入 "prototype" 来完成。将原型作为资产进行链接。当关键问题是"应该长什么样"或"应该如何运作"时使用。
• Grilling（HITL）：对话。这是默认情况。必须调用两次 Skill tool，分别传入 "grilling" 和 "domain-modeling"。
• Task（HITL 或 AFK）：在做出_决策_之前必须完成的手动工作：没有需要决定、制作原型或调研的内容，但讨论在其完成之前无法推进。例如注册某项服务以便评估其 API、开通访问权限、迁移数据以便查看其结构。这是唯一_执行_而非决策的类型，其价值在于解除某个决策的阻塞，而不是交付最终目标。Agent 能独自完成时由其推进（AFK）；否则将精确的清单交给人类（HITL）。完成工作后即视为解决；结果需记录已完成的操作以及后续工单所依赖的结果性事实（如凭据位置、新 URL、行数）。

战争迷雾

地图_有意_保持不完整：不要绘制你还看不清的部分。在现有工单之外，是战争迷雾：对那些你能察觉即将出现、但目前无法明确界定的决策与调查的模糊视图，因为它们依赖于仍未解决的问题。解决一个工单会清除其前方的迷雾，并将现已可明确界定的内容逐一转化为新工单，直到通往目标的路径清晰、不再有遗留工单为止。

地图中的尚未明确部分用于记录这种模糊视图：疑似的问题与之后需要重新审视的区域。它是通往目标的未探索前沿：其中的一切都在范围之内，只是还不够清晰，无法立为工单。可以按视图允许的程度或详或略地书写；它同时也是供协作者了解工作方向的路标。

迷雾还是工单？ 判断标准是你现在能否精确地陈述这个问题，_而不是_你现在能否回答它。

• 当问题已经明确时立为工单，即使它被阻塞、暂时无法行动。
• 当你还无法如此精确地表述时，列入尚未明确。不要把迷雾预先切分成工单大小的片段：它比工单更粗略，一个条目在前沿抵达时可能转化为多个工单，也可能一个都不转化。

尚未明确不包括已决定的内容（已做出的决策）、已存在的现行工单，以及超出范围的内容（下一节）。

超出范围

迷雾只会朝着目的地收敛。目的地界定了范围，因此超出范围的工作就是超出范围：它不是迷雾，也不属于尚未明确。它会在地图上单独列入超出范围部分：你有意识地排除在_本次_工作之外的事项。决定它归入此处的是范围，而非清晰度。

超出范围的工作永远不会进入前沿（前沿止于目的地），因此只有在重新绘制目的地时才会再次出现，而且届时它属于一项全新的工作，而不是继续之前的工作。

将某事排除在范围之外是一项范围界定行为，而不是路线上的一步。如果现有工单后来被发现位于目的地之外（绘制路线时误纳入范围，或在问题得到明确后才显露出来），就关闭它（已关闭的工单明确不在前沿上），并在超出范围部分留下一行说明：概述该事项及其超出范围的原因，并链接到已关闭的工单。它不会列入迄今的决策，因为该部分记录的是实际走过的路线；范围边界并不是路线上的一步。

调用方式

有两种模式。无论哪种，每个会话最多只能解决一个工单，研究工单除外。

绘制地图

用户提出一个宽泛的想法。

1. 明确目的地。 针对 "grilling" 和 "domain-modeling" 各调用一次 Skill 工具，以确定这张地图要找出的目标：规范、决策或变更。目的地界定范围，因此要先确定。
2. 绘制前沿。 再次进行 grilling，不过这次要按广度优先的方式：全面探索整个空间，而不是深入某个单独的主题，找出尚未确定的决策，以及现在可以采取的第一步。如果没有发现任何迷雾（前往目的地的路线已经清晰，整个旅程小到可以在一个会话内完成），就不需要绘制地图。停止并询问用户希望如何继续。
3. 创建地图（标签为 wayfinder:map）：填写 Destination 和 Notes，Decisions-so-far 留空，并将迷雾概略地写入尚未明确部分。
4. 创建现在可以明确具体内容的工单，作为地图的子问题，然后在第二轮中关联阻塞关系（问题需要先有 ID，才能相互引用）。关联后即可区分前沿和受阻事项；尚无法明确具体内容的部分都留在迷雾中，即尚未明确部分。
5. 启动研究子 Agent。 对于刚创建的每个 research 工单，启动一个子 Agent，调用 Skill 工具并传入 "research"，并行解决该工单；将其发现记录在临时的 research/<name> 分支上，并从工单附上上下文指针。
6. 停止：绘制地图是一项单会话工作；不直接解决任何问题。

沿地图推进

用户通过地图（URL 或编号）调用。

1. 加载地图：查看低分辨率概览，而不是每个工单的正文。
2. 选择工单。如果用户指定了工单，就使用该工单；否则按顺序选择前沿中的第一个工单。认领它：开始工作前先将它分配给自己。
3. 解决工单。按需深入查看：需要时获取任何相关工单或已关闭工单的完整正文；调用 ## Notes 区块中提到的技能。若不确定，就针对 "grilling" 和 "domain-modeling" 各调用一次 Skill 工具。
4. 记录解决结果：将答案作为解决结果评论发布，关闭问题，并在地图的 Decisions-so-far 中追加上下文指针。
5. 添加新发现的工单（先创建，再关联）；将答案使其变得可明确具体的迷雾内容提升为工单，并从尚未明确中清除每一块已提升的内容，使其只存在于对应的新工单中。如果答案表明某个工单（当前工单或其他工单）位于目的地之外，就将其排除在范围之外，而不是在路线中解决。如果某项决策使地图的其他部分失效，就更新或删除相应工单。

用户可能会并行处理未受阻的工单，因此要预期其他会话也在同时编辑跟踪器。