wayfinder

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

每项工作的目的地各不相同，而绘制地图的第一步就是为它命名：它会影响每张工单。目的地可以是交付后继续迭代的规范、开始规划前必须敲定的决策，也可以是在原地完成的变更，例如数据结构迁移。这张地图不限定领域：工程工作、课程内容，凡是符合这种形式的工作都适用。

规划，而非执行

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

按名称引用

每张地图和工单都是一个 issue，因此都有一个名称：它的标题。在人类阅读的所有内容中（叙述、地图的“迄今为止的决策”），都用名称指代它，绝不要只用 ID、编号或 slug。满屏的 #42, #43, #44 难以阅读；名称一目了然。ID 和 URL 并不会消失；名称会包含它们的链接，但它们必须_包含在_名称中，而不能取代名称。

地图

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

地图是一个索引，不是存储库。它列出已做出的决策，并指向存有详细信息的工单；每项决策只在一个地方记录，也就是对应的工单。因此，地图绝不重述决策，只概述并附上链接。

地图、子工单、阻塞关系和前沿查询的实际存放位置因跟踪器而异。 应该已经为你提供了 issue 跟踪器；如果没有，请运行 /setup-skills。请查阅跟踪器文档中的“Wayfinding operations”部分，了解_此_仓库如何处理这些事项。如果没有提供跟踪器，则默认使用本地 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 之一（参见工单类型）。wayfinder: 标签是地图及其工单所带的唯一标签，绝不能带 ready-for-agent 之类的分流标签：它们代表决策，而非实现工作。

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

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

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

票据类型

每个票据要么是 HITL（人在回路中，由代表自己发言的人协同完成），要么是由 Agent 单独驱动的 AFK。HITL 票据只有通过与真人的实时交流才能解决；Agent 绝不能代替真人发言（如果一个盘问型 Agent 自问自答，就说明流程出了问题）。

• Research（AFK）：阅读文档、第三方 API 或知识库等本地资源，以找出某项决策所需的事实。由调用 Skill 工具并使用“research”的 subagent 解决。需要当前工作目录之外的知识时使用。
• Prototype（HITL）：通过制作廉价、粗略且具体的制品来提升讨论的清晰度，例如大纲、初步方案、存根，或通过 Skill 工具编写 UI／逻辑代码，供人反馈。将原型作为资源链接。关键问题是“它应该是什么样子”或“它应该如何运行”时使用。
• Grilling（HITL）：一次只问一个问题的对话。默认类型。始终调用 Skill 工具并使用“grilling”。
• Task（HITL 或 AFK）：必须先完成的人工工作，完成后才能做出_决策_：没有需要决定、原型制作或研究的内容，但讨论会因此受阻。例如注册服务以评估其 API、配置访问权限，或移动数据以便查看其结构。这是唯一一种侧重_执行_而非决策的类型；它的价值在于解除决策阻碍，而非交付最终目标。Agent 能独自完成时由其驱动（AFK）；否则就向真人提供一份精确的检查清单（HITL）。工作完成后即可解决；答案会记录已完成的工作及其产生的事实（凭据位置、新 URL、行数等），供后续票据依赖。

战争迷雾

这张地图_刻意_保留不完整：看不到的内容就不要规划。当前票据之外就是战争迷雾：你能看出后续将有决策和调查，但由于它们依赖尚未解决的问题，暂时无法明确具体内容。解决一个票据会驱散前方的迷雾，将现在能够明确的事项逐一拆分为新票据，直到通往目标的道路清晰，且不再有剩余票据。

地图上的 Not yet specified 部分用于记录这片模糊区域：可能存在的问题，以及日后需要重新审视的范围。它是通往目标的未知前沿：这里的所有内容都在范围之内，只是还不够明确，无法列为票据。根据当前认知，内容可以写得宽泛，也可以写得详尽；它同时也是协作者了解工作方向的路标。

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

• 满足以下情况时建立票据：问题已经明确，即使它受阻、暂时无法处理也一样。
• 满足以下情况时标记为 Not yet specified：问题还无法表述得那么明确。不要提前把迷雾切分成票据大小的部分：迷雾的范围比票据更粗略；当前沿推进到那里时，一片迷雾可能会拆分成多个票据，也可能一个都不产生。

Not yet specified 不包括已经确定的内容（Decisions so far）、当前已有的票据，以及不在范围内的内容（下一节）。

超出范围

Fog 始终只会朝着目的地收敛。目的地界定了范围，因此超出它的工作超出范围：它不是 Fog，也不属于尚未明确。它会在地图上单独列入超出范围部分：也就是你有意排除在_本次_工作之外的内容。是否属于范围，而非明确程度，决定了它归入这里。

超出范围的工作永远不会进入下一阶段（边界止于目的地），因此只有在重新绘制目的地时才会重新出现，而且会作为一项全新的工作，而不是继续之前的工作。

将某项工作排除在范围之外是一项范围界定行为，而非路线上的一步。如果发现一个已存在的工单位于目的地之外（在绘制路线时被错误纳入，或在明确范围时才暴露出来），请关闭它（已关闭的工单明确不在边界内），并在超出范围部分留下一行：简述其内容以及超出范围的原因，并链接到已关闭的工单。它不属于迄今为止的决定，因为该部分记录的是实际走过的路线；范围边界不是路线上的一步。

调用方式

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

绘制地图

用户带着一个宽泛的想法发起调用。

1. 确定目的地。 使用“grilling”调用 Skill 工具，明确这张地图要通向什么：规格说明、决策或变更。目的地界定了范围，因此要先确定它。
2. 绘制边界。 再次进行梳理，这次要采用广度优先的方式：全面探索整个领域，而不是深入某一条线索，从而找出待决策事项和当前可采取的第一步。如果没有发现任何迷雾（通往目的地的路径已经清晰，整个旅程小到一次会话就能完成），则无需绘制地图。请停下来询问用户希望如何继续。
3. 创建地图（标签为 wayfinder:map）：填写目的地和备注，将迄今为止的决定留空，并将迷雾概述在尚未明确部分。
4. 创建现在就能明确的工单，将其设为地图的子议题，然后在第二轮中添加阻塞关系（议题必须先有 ID，才能相互引用）。这一轮也要写入交叉引用，并使用真实 ID：占位符 #<n> 会自动链接到无关议题。添加关系后，这些工单会归入边界内或被阻塞部分；所有目前还无法明确的内容都留在迷雾中，即尚未明确部分。
5. 启动研究子 Agent。 对于刚创建的每个 research 工单，启动一个子 Agent，调用 Skill 工具并使用“research”并行处理；将研究结果保存到临时的 research/<name> 分支，并通过工单中的上下文指针关联。推送该分支，但不要创建 PR：该分支绝不会合并。
6. 停止：绘制地图只占用一次会话；不手动解决任何工单。

推进地图

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

1. 加载地图：查看低分辨率视图，而不是每张工单的正文。
2. 选择工单。如果用户指定了工单，就处理该工单；否则按顺序选择排在最前的前沿工单。认领工单：在开始任何工作之前，将工单分配给自己。
3. 根据工单的 wayfinder:<type> 标签所标示的类型来解决工单（参见工单类型）。查看标签，而不只是正文：正文不会说明类型。按需查看详情：按需获取任何相关或已关闭工单的完整正文；对于 ## Notes 块中提到的技能，调用 Skill 工具。如有疑问，使用「grilling」调用 Skill 工具。
4. 记录解决结果：以解决说明评论的形式发布答案，关闭问题，并在地图的「迄今为止的决策」中追加上下文指针。
5. 添加新出现的工单（先创建，再建立关联）；将答案已使其可以明确说明的任何模糊事项转为工单，并从尚未明确中清除每项已明确的内容，使其仅保留在对应的新工单中。如果答案表明某张工单（当前工单或其他工单）不在目标范围内，将其排除在范围之外，而不是在处理路径上解决它。如果该决策会使地图的其他部分失效，请更新或删除那些工单。

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