wayfinder

一个模糊的想法来了——大到一个 agent 会话装不下，而且笼罩在迷雾之中：从这里出发到计划的路线还看不见。本技能将其绘制为 Issue 跟踪器上的共享地图，然后逐个处理其 ticket。地图是领域无关的——工程工作、课程内容，无论什么形态都适用。

用名称来引用

每个地图和 ticket 都是一个 issue，因此它有一个名称——它的标题。在人读取的一切内容中——叙述、地图的"已有决策"部分——都通过名称来引用，绝不使用原始 ID、编号或短横线标识。一堵 #42, #43, #44 组成的墙难以阅读；名称则一目了然。ID 和 URL 不会消失——但名称包裹着链接——它们只是活在名称内部，而不是替代它。

地图

地图是此仓库 Issue 跟踪器上的一个 issue，带有 wayfinder:map 标签——这是权威产出物。它的 ticket 是地图的子 issue。

地图是一个索引，而不是仓库。它列出已做出的决策并指向包含其细节的 ticket；一个决策只存在于一个地方——它的 ticket 中——因此地图从不重述它，只摘要它并链接。

地图、其子 ticket、阻塞关系和前沿查询在物理上位于何处，取决于具体的跟踪器。 查阅 docs/agents/issue-tracker.md（"Wayfinding 操作"一节）了解此仓库如何表达它们。如果该文档不存在，则默认使用本地 Markdown 跟踪器。

地图正文

整个地图以低分辨率加载，每个会话一次。打开的 ticket 不在此列出——它们是打开的子 issue，通过查询找到。

## 笔记

<领域；每个会话应查阅的技能；此工作的固定偏好>

## 已有决策

<!-- 索引——每个已关闭 ticket 一行：足以判断相关性，然后点击链接获取 ticket 中的详细内容 -->

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

## 迷雾

<!-- 见"战争迷雾"了解归属内容 -->

Ticket

每个 ticket 都是地图的子 issue；跟踪器的 issue ID 是其标识。其正文是问题，大小限制在一次 100K token 的 agent 会话：

## 问题

<该 ticket 解决的决策或调查>

每个 ticket 带有 wayfinder:<type> 标签——research、prototype、grilling、task 之一（见 Ticket 类型）。

一个会话通过将 ticket 分配给推动地图的开发人员来认领它，先做这个，在开始任何工作之前，这样并发会话会跳过它。那个分配人就是认领：一个打开的、未分配的 ticket 就是未被认领的。

阻塞关系使用跟踪器的原生依赖关系——这很关键，因为它能让前沿在视觉上呈现在跟踪器自己的 UI 中，让人可以在不打开地图的情况下看到哪些是可领取的。只有当一个跟踪器缺少原生阻塞功能时才回退到正文约定。一个 ticket 在所有阻塞它的 ticket 都关闭时即为已解除阻塞；前沿就是打开的、未阻塞的、未分配的子 ticket——已知领域的边界。

答案不是正文的一部分——它是在解决时记录的（见推进地图）。在解决 ticket 过程中创建的资产通过链接关联到 issue，而不是粘贴进去。

Ticket 类型

• Research：阅读文档、第三方 API 或本地资源如知识库。创建一个 Markdown 摘要作为链接的资产。当需要当前工作目录之外的知识时使用。
• Prototype：通过制作一个廉价、粗略、具体的人工产物来提高讨论的逼真度——大纲、初期草稿、桩代码、或通过 /prototype 技能实现的 UI/逻辑代码。将原型作为资产链接。当"它应该是什么样子"或"它应该表现为什么行为"是关键问题时使用。
• Grilling：与 agent 的对话。使用 /grilling 和 /domain-modeling 技能。一次问一个问题。默认情况。
• Task：推进讨论所必需的纯手动工作——无需决策、原型或研究。迁移数据、注册服务、配置访问权限。Agent 在可能时自动化它；否则交给用户一份精确的检查清单。在工作完成时视为已解决；答案记录做了什么以及后续 ticket 依赖的任何衍生事实（凭据位置、新 URL、行数）。

战争迷雾

地图是故意不完整的：不要绘制你还看不到的东西。在 ticket 之后是迷雾——你能感觉到将要到来但还无法确定的决策和调查的依稀影像，因为它们取决于仍悬而未决的问题。解决一个 ticket 会清除它前方的迷雾，将现在可明确的内容毕业为新的 ticket——一次一个，直到通往目标的道路清晰，不再有 ticket 留存。

地图的迷雾部分就是写下那个依稀影像的地方：怀疑的问题、稍后要重新审视的区域、你暂缓的风险。尽情地写得粗略或完整，取决于可见度；它同时作为协作者的指示牌，指引工作的方向。

迷雾还是 ticket？ 检验标准是你现在是否能精确陈述问题——不是你能否现在回答它。

• Ticket 当问题已经清晰——即使它被阻塞，你还不能对其采取行动。
• 迷雾当你还没法说得那么清楚。不要把迷雾预先切成 ticket 大小的块：它比 ticket 粗糙，迷雾中的一片区域可能会毕业成几个 ticket，也可能没有，取决于前沿何时到达它。

迷雾只排除已经决定的内容（那是"已有决策"）和已经是 ticket 的内容。

调用方式

两种模式。任一种情况下，每个会话最多解决一个 ticket。

绘制地图

用户用一个模糊的想法来调用。

1. 运行 /grilling 和 /domain-modeling 会话以浮现开放的决策。
2. 创建地图（标签 wayfinder:map）：填写笔记，已有决策为空，勾勒迷雾。
3. 创建你现在可以明确的 ticket 作为地图的子 issue——然后在第二轮中设置阻塞关系（issue 需要先有 ID 才能相互引用）。连线将它们归类为前沿和被阻塞；你还不能明确的一切留在迷雾中。
4. 停止——绘制地图是一个会话的工作；不要在同一个会话中也解决 ticket。

推进地图

用户用地图（URL 或编号）来调用。ticket 是可选的——没有指定时，你选取下一个决策，而不是用户。

1. 加载地图——低分辨率视图，不包括每个 ticket 正文。
2. 选择 ticket。如果用户指定了一个，使用它。否则按顺序取第一个前沿 ticket。认领它：在开始任何工作之前将其分配给自己。
3. 解决它——按需放缩：在需要时获取任何相关或已关闭 ticket 的完整正文；调用 ## Notes 块中指定的技能。有疑问时使用 /grilling 和 /domain-modeling。
4. 记录解决结果：将答案发表为解决评论，关闭 issue，并在地图的"已有决策"中追加一条上下文指针。
5. 添加新浮现的 ticket（创建再连线）；升级因该答案而变得可明确的迷雾内容，从迷雾中清除每个已升级的碎片，使其只存在于新 ticket 中。如果该决策使地图的其他部分失效，更新或删除那些 ticket。

用户可能并行运行未阻塞的 ticket，因此要预期其他会话可能同时在编辑跟踪器。