wayfinder

一个模糊的想法来了——大到一个 agent 会话装不下，而且笼罩在迷雾之中：从当前位置到目的地的路线还不 visible。Wayfinding 就是寻找那条路线，而不是冲向目的地。本技能将其绘制为 Issue 跟踪器上的共享地图，然后逐个处理其决策 ticket——问题本身，其答案是一个决策，而非构建中的可交付物切片——直到路线清晰。

每个项目的目标各不相同，命名目标是绘图的第一个行为——它塑造了每一个 ticket。它可能是一份要交付并迭代的规格说明、一个在规划开始前要锁定的决策、或者一个原地进行的变更（如数据结构迁移）。地图是领域无关的——工程工作、课程内容，无论什么形态都适用。

规划，而非动手

Wayfinder 默认是规划工具：每个 ticket 解决一个决策，地图在路线清晰时完成——不再有任何需要决定的事情，就可以交给别人去动手了。想要直接动手做的冲动，通常是你已经抵达地图边缘的信号，是时候交接了。项目可以在其笔记中覆盖这一设定——将执行任务也纳入地图——但默认情况下，产出的是决策，而非可交付物。

用名称来引用

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

地图

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

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

地图、其子 ticket、阻塞关系和前沿查询在物理上位于何处，取决于具体的跟踪器。 Issue 跟踪器应已提供给你——如果没有，请告诉用户运行 /setup-matt-pocock-skills。查阅跟踪器文档的"Wayfinding 操作"一节了解此仓库如何表达它们。如果未提供跟踪器，默认使用本地 Markdown 跟踪器。

地图正文

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

## 目的地

<到达此地图终点时的样子——该目标最终产出的规格、决策或变更。一两行；每个会话在选择 ticket 前都会以此为导向。>

## 笔记

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

## 已有决策

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

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

## 尚未明确

<!-- 见"战争迷雾"：范围内的迷雾，尚不能创建 ticket；随着前沿推进而毕业-->

## 范围外

<!-- 见"范围外"：目的地之外排除的工作；已关闭，永不毕业-->

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，而不是粘贴进去。