wayfinder

一个模糊的想法出现了，它大到无法在一个 Agent 会话中完成，而且笼罩在迷雾中：从这里到目的地的路目前还看不见。Wayfinding 的目标是找到这条路，而不是径直冲向目的地。这项技能会在仓库的议题跟踪器上绘制一张共享地图，然后逐一处理其中的决策工单（需要通过解决问题来做出决策，而不是拆分出要执行的构建任务），直到路线清晰为止。

不同的工作有不同的目的地，而绘制地图的第一步就是明确目的地：它会影响每张工单。目的地可能是一份要交接并迭代完善的规范、一项必须在开始规划前敲定的决策，或是一项直接就地完成的变更，例如数据结构迁移。这张地图与领域无关：无论是工程工作、课程内容，还是其他符合这种形式的工作，都可以使用。

规划，而非执行

Wayfinder 默认用于规划：每张工单都会解决一个决策；当路线清晰，且在有人着手执行前不再有待决事项时，地图就算完成。想要直接动手的冲动，通常意味着你已经走到了地图的边缘，是时候交接了。某项工作可以在其备注中明确覆盖这一默认设定，将执行纳入地图；但除非有此说明，否则产出决策，而非交付物。

按名称引用

每张地图和每张工单都是一个议题，因此都有一个名称：它的标题。在人类阅读的所有内容中（叙述、地图的「已做出的决策」），都要用名称来指代它，绝不能只用 ID、编号或 slug。满屏的 #42, #43, #44 难以辨认；名称一眼就能读懂。ID 和 URL 仍然存在；名称会包裹链接，但它们位于名称_内部_，绝不能取代名称。

地图

地图是此仓库议题跟踪器上的单个议题，标记为 wayfinder:map，是规范的产物。地图的工单是它的子议题。

地图是一个索引，不是存储库。它列出已做出的决策，并指向包含详细内容的工单；每项决策只存在于一个地方，也就是它对应的工单，因此地图不会重述决策，只会简要概述并附上链接。

地图、子工单、阻塞关系和前沿查询的实际存放位置因跟踪器而异。 应该已经为你提供了议题跟踪器。如果没有，请告诉用户运行 /setup-matt-pocock-skills。请查阅跟踪器文档的「Wayfinding operations」部分，了解_此_仓库如何表示这些内容。如果未提供跟踪器，默认使用本地 Markdown 跟踪器。

地图正文

整张地图以低分辨率呈现，每个会话加载一次。不会列出未关闭的工单：它们是未关闭的子议题，应通过查询查找。

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

工单

每张工单都是地图的一个子议题；跟踪器的议题 ID 即为其标识。工单正文是一个问题，规模适合在一个 100K token 的 Agent 会话中解决：

## Question

<the decision or investigation this ticket resolves>

每张工单都带有一个 wayfinder:<type> 标签，类型为 research、prototype、grilling、task 之一（参见工单类型）。

会话会先将工单分配给负责推进地图的开发者，以此认领工单，然后才开始工作，这样并发会话就会跳过它。该受派人_就是_认领者：未关闭且无人受派的工单即为未认领工单。

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

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

工单类型

每个工单要么是 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. 添加新发现的工单（先创建，再关联）；将答案使其变得可明确具体的迷雾内容提升为工单，并从尚未明确中清除每一块已提升的内容，使其只存在于对应的新工单中。如果答案表明某个工单（当前工单或其他工单）位于目的地之外，就将其排除在范围之外，而不是在路线中解决。如果某项决策使地图的其他部分失效，就更新或删除相应工单。

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