wayfinder

一个模糊的想法出现了，它规模太大，无法在一次 Agent 会话中完成，并且笼罩在迷雾中：从这里通往 目的地 的路径尚不可见。Wayfinding 的重点是找到这条路，而不是直接冲向目的地。本技能将这条路绘制为代码仓库议题跟踪器上的一份共享地图，然后逐一处理其中的决策工单（这类问题的解决结果是一项决定，而不是需要执行的构建切片），直到路线清晰。

目的地因项目而异，而命名目的地是绘图的第一步，它会影响每一张工单。目的地可能是一份需要交接并持续迭代的规格说明，可能是一项需要在规划开始前锁定的决定，也可能是一次原地进行的变更，例如数据结构迁移。该地图与领域无关：工程工作、课程内容或其他符合此结构的内容都适用。

规划，而非执行

Wayfinder 默认进行规划：每张工单解决一项决定，当路线清晰、无需再做决定即可由人去执行时，地图即告完成。想直接动手做的冲动通常说明已经到达地图的边缘，是时候交接了。项目可以在其备注中覆盖这一默认设定，将执行纳入地图本身，但在没有此类说明时，只产出决定，而不产出交付物。

按名称引用

每份地图和每张工单都是一个议题，因此都有一个名称，即其标题。在所有供人阅读的内容中（叙述文字、地图的「已做决定」部分），都应使用该名称来引用，绝不要只用裸 id、编号或 slug。满屏的 #42, #43, #44 难以辨认，名称一眼即可读懂。id 和 URL 并不会消失：名称包裹其链接，但二者都位于名称_之内_，不能取代名称。

地图

地图是这个仓库议题跟踪器上的单个议题，带有 wayfinder:map 标签，是权威的产物。它的工单是该地图的子议题。

地图是索引，而不是存储。它列出已做出的决定，并指向承载其详细内容的工单；每项决定只存在于一个地方，即其工单中，因此地图从不重复陈述决定，只做概括并附上链接。

地图、其子工单、阻塞关系以及前沿查询在跟踪器中的具体存放方式因跟踪器而异。 议题跟踪器应当已经提供给你。如果没有，请告知用户运行 /setup-matt-pocock-skills。请查阅跟踪器文档中的「Wayfinding 操作」章节，了解_本仓库_如何表达这些内容。如果没有提供任何跟踪器，则默认使用本地 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 之一（参见工单类型）。wayfinder: 标签是地图及其工单唯一可以携带的标签，绝不使用 ready-for-agent 之类的分类标签：它们是决定，而不是实现工作。

会话在开始任何工作之前，首先将工单分配给驱动该地图的开发者，以此认领该工单，从而使并发会话跳过它。这个负责人_就是_认领记录：未关闭且未分配的工单即为未认领。

阻塞关系使用跟踪器的原生依赖关系。这一点至关重要，因为它能在跟踪器自身的 UI 中_直观地_呈现前沿，让人无需打开地图就能看到哪些工单可以着手处理。只有缺少原生阻塞功能的跟踪器，才退而使用正文约定。当阻塞该工单的所有工单都已关闭时，该工单即为未阻塞；前沿则是未关闭、未阻塞且未认领的子工单，也就是已知范围的边缘。

答案不属于正文内容，而是在解决工单时记录下来（参见逐个处理地图）。解决工单时创建的资产应从议题中链接，而不是直接粘贴进来。

工单类型

每张工单要么是 HITL（人机协作，由代表自己发言的人参与处理），要么是 AFK，完全由 Agent 驱动。HITL 工单只能通过实时交流来解决；Agent 绝不能代替人类发言（如果一个盘问式 Agent 自己回答自己的问题，就违背了这一原则）。

• Research（AFK）：阅读文档、第三方 API 或知识库等本地资源，以查明决策所需的事实。由加载「research」技能（阅读其 SKILL.md）的子 Agent 解决。需要了解当前工作目录之外的信息时使用。
• Prototype（HITL）：通过加载「prototype」技能（阅读其 SKILL.md），制作一个低成本、粗略但具体的产物（大纲、粗略方案、存根或 UI／逻辑代码），供讨论反馈，以提升讨论的具体程度。将原型作为素材链接。关键问题是「它应该是什么样」或「它应该如何运作」时使用。
• Grilling（HITL）：对话。默认类型。始终加载两项技能：「grilling」和「domain-modeling」（阅读各自的 SKILL.md 并遵循其中说明）。
• Task（HITL 或 AFK）：在做出 决策 前必须完成的手动工作：没有需要决定、制作原型或研究的内容，但讨论会因这项工作而受阻。例如，注册服务以评估其 API、开通访问权限，或移动数据以查看其结构。这是唯一一种以实际行动为主、而非做决策的类型；它之所以必要，是因为能解除决策的阻碍，而非直接交付最终目标。Agent 能独立完成时由其驱动（AFK）；否则会向人类提供一份明确的检查清单（HITL）。工作完成后即视为解决；答案会记录已完成的工作以及由此得到的事实（凭据位置、新 URL、行数），供后续工单依赖。

战争迷雾

地图 刻意 保持不完整：不要绘制尚未看清的部分。当前工单之外就是战争迷雾：你能预见即将出现的决策和调查，却还无法明确界定它们，因为它们取决于尚未解决的问题。解决一张工单，就会驱散其前方的迷雾，将如今已能明确界定的事项逐一拆分为新工单，直到通往目标的道路清晰且不再有工单为止。

地图中的 尚未明确部分用于记录这种模糊的前景：推测中的问题，以及之后需要重新审视的领域。这是通往目标的未知前沿：这里的所有内容都在范围内，只是还不够明确，无法建立工单。根据当前所能了解的情况，尽量简略或详细地记录；它也兼作路标，帮助协作者了解工作方向。

**是迷雾还是工单？**判断标准是你现在能否准确表述问题，_而不是_现在能否回答问题。

• **满足以下情况时建立工单：**问题已经明确，即使当前受阻、还无法着手处理。
• **满足以下情况时标记为尚未明确：**你还无法准确表述问题。不要预先把迷雾切成工单大小的块：迷雾的颗粒度比工单更粗；当前沿推进到那里时，一片区域可能会细化为多张工单，也可能一张都没有。

尚未明确不包括已决定的事项（迄今的决策）、当前已有的工单，以及不在范围内的事项（见下一节）。

范围之外

雾只会朝着目的地汇聚。目的地确定了范围，因此超出范围的工作属于范围之外：它不是雾，也不属于尚未明确。地图上会为它单独设立范围之外一节：记录你有意识地排除在_本次_工作之外的内容。将它归入此处的依据是范围，而不是明确程度。

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

将某项工作排除在范围之外，是一项范围界定行为，不是路线上的一步。当发现某张已有工单位于目的地之外（绘制地图时误纳入范围，或在明确过程中显露出来），请关闭它（已关闭的工单明确不在前沿上），并在范围之外一节中留下一行记录：概述内容及其超出范围的原因，并链接到已关闭的工单。它不会列入迄今为止的决策，因为该部分记录的是实际走过的路线；范围边界不是路线上的一步。

调用

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

绘制地图

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

1. 确定目的地。 加载“grilling”和“domain-modeling”技能（阅读各自的 SKILL.md 并遵循其中的指引），明确这张地图要找到什么：规范、决策或变更。目的地确定了范围，因此要先确定目的地。
2. 绘制前沿。 再次进行 grilling，这次采用广度优先：遍历整个领域，而不是深入某一条线索，找出尚未解决的决策以及当前可以采取的第一步。如果没有发现任何雾（通往目的地的路径已经清晰，整个过程也小到足以在一个会话中完成），就不需要绘制地图。停止并询问用户希望如何继续。
3. 创建地图（标签为 wayfinder:map）：填写 Destination 和 Notes，将 Decisions-so-far 留空，并将雾概略记录在尚未明确中。
4. 创建当前可以明确的工单，将其作为地图的子议题，然后在第二轮中添加阻塞关系（议题必须先有 ID 才能相互引用）。这一轮也要写入交叉引用，并使用真实 ID：占位符 #<n> 会自动链接到无关议题。添加关系会将它们划分到前沿和受阻项中；所有尚无法明确的内容都留在雾中，也就是尚未明确一节。
5. 启动研究子 Agent。 对于刚创建的每张 research 工单，启动一个子 Agent，使其加载“research”技能（阅读其 SKILL.md），并行解决该工单，将研究发现保存在临时的 research/<name> 分支上，并在工单中附上上下文指针。推送该分支，但不要创建 PR：它永远不会被合并。完成结果会以推送的形式到达，并附上研究发现文件的路径：推送到达后读取该文件；或者，由于研究以会话为范围且绘图到此结束，如果运行在本会话结束前未完成，则在之后的会话中从分支上已保存的检查点研究发现继续。
6. 停止：绘图属于一个会话的工作；不在此过程中手动解决任何工单。

按地图推进

用户会通过地图（URL 或编号）发起任务。工单是可选的：没有指定工单时，由你而不是用户选择下一个决策。

1. 加载地图：查看低分辨率视图，不要加载每张工单的正文。
2. 选择工单。如果用户指定了工单，就使用该工单；否则按顺序选择第一个前沿工单。认领它：开始处理前先将工单分配给自己。
3. 按其 wayfinder:<type> 标签指定的类型解决工单（参见工单类型）。查看标签，而不只是正文：正文不会说明类型。按需放大：需要时获取任何相关或已关闭工单的完整正文；加载 ## Notes 区块中提到的技能（阅读每个 SKILL.md 并遵循其中的说明）。如有疑问，加载 "grilling" 和 "domain-modeling"（阅读每个 SKILL.md 并遵循其中的说明）。
4. 记录解决方案：将答案作为解决方案评论发布，关闭问题，并在地图的 Decisions-so-far 中追加一个上下文指针。
5. 添加新发现的工单（先创建，再关联）；将答案已使其可明确界定的任何模糊项转为正式工单，并从 Not yet specified 中清除各项已明确内容，使其仅保留在新工单中。如果答案表明某张工单（当前工单或其他工单）超出目的地范围，就将其排除在范围之外，而不是在路线中解决。如果该决策使地图的其他部分失效，请更新或删除相应工单。

用户可能会并行处理不受阻塞的工单，因此要预料到其他会话也在同时编辑跟踪系统。