wayfinder

name	wayfinder
description	将单个 Agent 会话无法容纳的大型工作规划成 Issue 跟踪器上的共享调查地图，并逐个解决工单，直到通往目标的路线清晰。
disable-model-invocation	true

一个松散想法刚刚出现：规模超过单个 Agent 会话，并且笼罩在迷雾中；从当前位置通往目标（destination）的路线尚不可见。Wayfinding 的任务是找到这条路，不能直接冲向终点。本 Skill 会在仓库的 Issue 跟踪器上绘制一张共享地图，再逐个处理地图中的工单，直到路线清晰。

每项工作的目标都不同，为目标命名是绘图的第一个动作，它会塑造之后的每张工单。目标可能是一份交给后续流程继续迭代的规格、一项必须在规划前确定的决策，也可能是直接在原处完成的变更，例如数据结构迁移。地图不限定领域：工程工作、课程内容或任何符合这种形态的任务都可以使用。

负责规划，不直接执行

Wayfinder 默认用于规划：每张工单解决一项决策；地图在路线已经清晰、真正执行工作前再无待决定事项时完成。想要直接动手，通常说明你已经到达地图边缘，应当进行交接。某项工作可以在 Notes 中覆盖这条默认规则，把执行本身纳入地图；没有明确覆盖时，产出决策，不产出交付物。

使用名称引用

每张地图和工单都是一个 Issue，因此都有自己的名称，也就是标题。在所有供人阅读的内容中，包括过程叙述和地图的 “Decisions so far”，都要用名称引用，绝不能只写裸露的 id、编号或 slug。满墙的 #42, #43, #44 无法快速阅读；名称一眼即可理解。id 和 URL 仍然保留，但应包裹在带链接的名称中，不能代替名称本身。

地图

地图是当前仓库 Issue 跟踪器中的一个独立 Issue，带有 wayfinder:map 标签；它是标准产物。地图工单作为它的子 Issues 存在。

地图是一份索引，不是内容存储区。它列出已经作出的决策，并指向保存细节的工单。一项决策只存在于一个位置，也就是对应工单；地图只写摘要并提供链接，绝不再次完整叙述。

地图、子工单、阻塞关系和前沿查询具体保存在哪里，由跟踪器决定。 Issue 跟踪器应当已经配置；没有时运行 /setup-matt-pocock-skills。阅读跟踪器文档中的 “Wayfinding operations” 一节，了解当前仓库如何表达这些概念。尚未配置跟踪器时，默认使用本地 Markdown 跟踪器。

地图正文

这是整张地图的低分辨率视图，每个会话只加载一次。尚未关闭的工单不在正文中罗列；它们是打开状态的子 Issues，应通过查询获取。

## Destination

<走到地图终点时应得到什么：本次工作正在寻找的规格、决策或变更。用一两行写明；每个会话在选择工单前都先以此校准方向。>

## Notes

<所属领域；每个会话都应查阅的 Skills；本项工作长期适用的偏好>

## Decisions so far

<!-- 索引：每张已关闭工单一行。摘要只需足以判断相关性，细节通过链接进入工单查看。 -->

- [<已关闭工单标题>](link) — <答案的一行摘要>

## Not yet specified

<!-- 参见“战争迷雾”：尚无法形成工单的范围内迷雾；随着前沿推进逐渐转化。 -->

## Out of scope

<!-- 参见“范围之外”：已经确定超出目标的工作；保持关闭，永不转化。 -->

工单

每张工单都是地图的一个子 Issue；跟踪器中的 Issue id 就是它的身份。工单正文只写需要回答的问题，规模限制在一次 100K token 的 Agent 会话内：

## Question

<本工单要解决的决策或调查事项>

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

会话必须在开始任何工作前，先把工单分配给负责推进地图的开发者，以此完成认领，使并行会话能够跳过它。Assignee 就是认领标记：打开且无人分配的工单尚未被认领。

阻塞关系使用跟踪器的原生依赖功能。这一点很重要，因为跟踪器自身 UI 会直观显示前沿，使用户无需打开地图就能看到哪些工单可领取。只有不支持原生阻塞关系的跟踪器，才退回到正文约定。阻塞当前工单的所有工单都已关闭时，它属于未阻塞状态；**前沿（frontier）**由所有打开、未阻塞、未认领的子工单组成，也就是已知区域的边缘。

答案不写在工单正文中，而在解决工单时记录，参见推进地图。处理工单时创建的产物应通过链接附在 Issue 上，不能直接粘贴进去。

工单类型

每张工单要么属于 HITL，由能够亲自表达意见的人类参与完成；要么属于 AFK，由 Agent 独立推进。HITL 工单只能通过实时交流解决，Agent 永远不能替人类回答其应回答的部分。一个自行回答所有问题的 grilling Agent 已经违反了这条规则。

• Research（AFK）：阅读文档、第三方 API，或知识库等本地资源。产出一份 Markdown 摘要，并作为链接附加。需要当前工作目录之外的知识时使用。
• Prototype（HITL）：通过廉价、粗糙、具体的产物提高讨论保真度，让人能够针对实物作出反应；可以是大纲、初稿、stub，也可以通过 /prototype Skill 生成 UI 或逻辑代码。将原型作为产物链接。关键问题是“它应该长什么样”或“它应该如何表现”时使用。
• Grilling（HITL）：结合 /grilling 和 /domain-modeling Skills 进行对话，每次只问一个问题。这是默认类型。
• Task（HITL 或 AFK）：在作出某项决策前必须完成的人工工作。这里没有需要决定、制作原型或调查的内容，但工作未完成会阻塞讨论，例如注册服务以判断其 API、开通访问权限、移动数据以观察其形态。这是唯一一种会直接做事的类型；它存在的理由是解除决策阻塞，不能用于交付最终目标。Agent 能独立完成时按 AFK 推进，否则给人类一份准确清单，按 HITL 处理。工作完成时即可解决；答案中记录已完成事项，以及后续工单依赖的事实，例如凭据位置、新 URL、行数。

战争迷雾

地图被有意保持为不完整状态：看不清的部分不要提前绘制。现有工单之外是战争迷雾（fog of war）。你能够模糊预见将来需要作出的决策和调查，但由于它们依赖尚未解决的问题，目前无法准确描述。解决一张工单会清除前方迷雾，把现在已经能够描述的内容逐项转化为新工单；这个过程持续进行，直到通往目标的路线清晰，并且没有剩余工单。

地图的 Not yet specified 一节用于记录这种模糊视图：可能存在的问题、以后要重新审视的区域。它表示朝向目标、尚未发现的前沿；其中所有内容都属于当前范围，只是还没有清晰到足以形成工单。根据当前可见程度，可以写得很粗略，也可以较为完整。协作者阅读地图时，它同时提供方向提示。

迷雾还是工单？ 判断标准是现在能否准确写出问题，不能以现在是否能够回答问题为依据。

• 形成工单：问题已经足够清晰，即使它仍被阻塞、目前无法处理。
• 保留在 Not yet specified：目前还无法把问题表达得足够准确。不要预先把迷雾切成工单大小；迷雾的粒度比工单更粗，前沿到达后，一块迷雾可能转化为多张工单，也可能一张都不产生。

Not yet specified 不包含已经决定的事项（Decisions so far）、已经存在的开放工单，以及范围之外的工作（下一节）。

范围之外

迷雾只会朝向目标聚集。目标固定了范围，因此越过目标的工作属于范围之外；它不是迷雾，也不能放进 Not yet specified。地图使用单独的 Out of scope 一节，记录你有意识地从本次工作中排除的内容。进入这里的原因是范围，不是清晰度。

范围之外的工作永远不会转化为工单；前沿到达目标即停止。只有重新定义目标时，这些工作才会再次出现，并且应作为一项全新工作，不能恢复原地图继续推进。

把某项内容排除在范围外是一项范围界定动作，不是路线中的一个步骤。已经存在的工单后来被发现位于目标之外时，无论是绘图时错误纳入，还是其他工单的结论揭示了这一点，都应关闭它；关闭状态会明确将它移出前沿。同时在 Out of scope 中留一行：写出摘要和排除原因，并链接到已关闭工单。它不能进入 Decisions so far；后者只记录实际走过的路线，范围边界不属于路线步骤。

调用方式

有两种模式。无论采用哪一种，一个会话都绝不能解决超过一张工单。

绘制地图

用户以一个松散想法调用。

1. 为目标命名。 运行一次 /grilling 和 /domain-modeling 会话，确定地图最终通向什么：规格、决策或变更。目标决定范围，因此必须最先明确。
2. 绘制前沿。 再次进行追问，这次采用广度优先：横向展开整个空间，不能沿某一条分支深入；找出仍未解决的决策和现在即可采取的第一步。如果没有发现迷雾，说明通往目标的路线已经清晰，整个过程可以在一个会话中完成，不需要地图。停止并询问用户希望如何继续。
3. 创建地图，添加 wayfinder:map 标签：填写 Destination 和 Notes，保持 Decisions-so-far 为空，并把迷雾概括写入 Not yet specified。
4. 创建目前能够准确描述的工单，作为地图子 Issues。随后在第二轮连接阻塞关系，因为 Issues 必须先拥有 id 才能彼此引用。连接阻塞关系后，工单会分别进入前沿和阻塞状态；仍无法准确描述的内容继续留在 Not yet specified 的迷雾中。
5. 停止。绘制地图本身占用一个完整会话；本会话不能继续解决工单。

推进地图

用户通过地图 URL 或编号调用。指定工单属于可选项；未指定时，由你选择下一项决策，不要求用户选择。

1. 加载地图，只读取低分辨率视图，不能一次加载所有工单正文。
2. 选择工单。用户指定时采用该工单；否则按顺序选择第一张前沿工单。先认领：在开始任何工作前把它分配给自己。
3. 解决工单，并按需放大查看：需要时再获取相关工单或已关闭工单的完整正文；调用 ## Notes 中指定的 Skills。拿不准时使用 /grilling 和 /domain-modeling。
4. 记录解决结果：把答案发布为一条resolution comment，关闭 Issue，并在地图的 Decisions-so-far 中追加一个上下文指针。
5. 添加新发现的工单，先创建、再连接阻塞关系。把答案已经变得可描述的迷雾转化为工单，并从 Not yet specified 删除对应片段，使信息只保存在新工单中。如果答案揭示某张工单——当前工单或其他工单——位于目标之外，应将其排除在范围外，不能把它当作路线中的决策解决。如果当前决策使地图其他部分失效，更新或删除相应工单。

用户可能并行运行多个未阻塞工单，因此要预期其他会话会同时修改跟踪器。