wayfinder

name	wayfinder
description	规划超出一个 agent 会话容量的大块工作 —— 在 issue tracker 上建立一张调查 tickets 的共享地图，逐个解决它们，直到通往目标的路径清晰可见。
disable-model-invocation	true

一个模糊的想法出现了 —— 太大而无法放入单个 agent 会话，且笼罩在迷雾中：从当前状态到目标的路径尚不可见。寻路（Wayfinding）就是找到那条路，而非冲向目标。此技能在仓库的 issue tracker 上绘制路径作为一张共享地图，然后逐个处理其 tickets，直到路径变得清晰。

目标因工作而异，命名目标是绘制地图的第一步 —— 它塑造每个 ticket。目标可能是一份待移交和迭代的 spec、一个在规划开始前需锁定的决策、或是一个原地完成的变更（如数据结构迁移）。地图是领域无关的 —— 工程工作、课程内容，任何符合此形态的内容都可以。

规划，而非执行

Wayfinder 默认进行规划：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其Notes覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。

用名称引用

每张地图和每个 ticket 都是一个 issue，因此它有一个名称 —— 即其标题。在人类阅读的所有内容中 —— 叙述、地图的 Decisions-so-far —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 #42, #43, #44 的墙是难以阅读的；名称可以一目了然。ID 和 URL 不会消失 —— 名称包裹着其链接 —— 但它们在名称内部，绝不是名称的替代品。

地图

地图是本仓库 issue tracker 上的单个 issue，标记为 wayfinder:map —— 是规范的产物。其 tickets 是地图的子 issues。

地图是一个索引，而非存储。它列出已做出的决策并指向持有其详细信息的 tickets；一个决策只存在于一个地方 —— 其 ticket —— 因此地图从不重述，仅概括并链接。

地图、其子 tickets、阻塞关系和前沿查询的物理存放位置取决于 tracker。 Issue tracker 应已提供给你 —— 如果没有，运行 /setup-matt-pocock-skills。查阅 tracker 文档的"寻路操作"章节，了解此仓库如何表达这些内容。如果未提供 tracker，则默认使用本地 markdown tracker。

地图正文

整个地图的低分辨率视图，每个会话加载一次。开放的 tickets 不列出 —— 它们是通过查询找到的开放子 issues。

## 目的地

<到达此地图终点时的样子 —— 此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 ticket 之前以其为定位。>

## 说明

<领域；每个会话应咨询的技能；此工作的常设偏好>

## 已做出的决策

<!-- 索引 —— 每个已关闭 ticket 一行：足以判断相关性，然后放大链接查看 ticket 持有的详细信息 -->

- [<已关闭 ticket 标题>](link) —— <答案的一句话概括>

## 尚未明确

<!-- 参见"战争迷雾"：范围内但你尚无法做成 ticket 的迷雾；随着前沿推进而升级 -->

## 超出范围

<!-- 参见"超出范围"：被裁定在目标之外的工作；已关闭，永不升级 -->

Tickets

每个 ticket 是地图的子 issue；tracker 的 issue ID 是其标识。其正文是问题，大小适配一个 100K token 的 agent 会话：

## 问题

<此 ticket 要解决的决策或调查>

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

一个会话通过将 ticket 分配给驱动地图的开发者来领取它，在开始任何工作之前分配，以便并发会话跳过它。该分配者就是领取标记：一个开放、未分配的 ticket 是未被领取的。

阻塞关系使用 tracker 的原生依赖关系 —— 这很关键，因为它使前沿在 tracker 自己的 UI 中可视化呈现，因此人类无需打开地图就能看到哪些可以被领取。只有缺少原生阻塞功能的 tracker 才退回到正文约定。当一个 ticket 的所有阻塞 tickets 都已关闭时，该 ticket 是未被阻塞的；前沿是开放、未被阻塞、未被领取的子 issues —— 即已知的边界。

答案不是正文的一部分 —— 它在解决时记录（参见遍历地图）。解决 ticket 时创建的资产从 issue 链接，而非粘贴进去。

Ticket 类型

每个 ticket 要么是 HITL —— 人在回路中，与一个代表自己发言的人类一起工作 —— 要么是 AFK，由 agent 独立驱动。HITL ticket 只能通过实时交流来解决；agent 绝不代替人类一方发言（一个自问自答的质询 agent 已经破坏了这一点）。

• Research（AFK）：阅读文档、第三方 API 或知识库等本地资源。创建一个 markdown 摘要作为链接资产。当需要当前工作目录之外的知识时使用。
• Prototype（HITL）：通过制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或通过 /prototype 技能实现的 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
• Grilling（HITL）：通过 /grilling 和 /domain-modeling 技能逐个问题进行的对话。默认情况。
• Task（HITL 或 AFK）：在决策能够做出之前必须完成的手动工作 —— 没有需要决定、原型化或研究的内容，但讨论被阻塞直到完成。注册服务以便判断其 API、开通访问权限、移动数据以便看到其形态。这是唯一一个执行而非决策的类型 —— 它通过为决策解除阻塞来赢得其位置，而非通过交付目标。Agent 在可能的情况下独立驱动（AFK）；否则它交给人类一份精确的清单（HITL）。当工作完成时解决；答案记录已完成的工作以及后续 tickets 依赖的任何结果性事实（凭据位置、新 URL、行数）。

战争迷雾

地图是刻意不完整的：不要绘制你还看不到的内容。在活跃的 tickets 之外是战争迷雾 —— 你能感觉到即将到来但尚无法确定的决策和调查的模糊视野，因为它们依赖于尚未解决的问题。解决一个 ticket 会清除它前方的迷雾，将任何现在可以明确的内容升级为新的 tickets —— 逐个进行，直到通往目标的路径清晰且没有剩余 tickets。

地图的尚未明确章节记录这些模糊视野：待定的问题、后续重新审视的区域。它是朝向目标方向的未发现前沿 —— 此处的所有内容都在范围内，只是不够清晰以做成 ticket。根据视野允许的范围，尽可能松散或完整地书写；它同时也是协作者阅读工作方向的路标。

迷雾还是 ticket？ 判断标准是你是否现在就能精确地陈述问题 —— 而不是你现在是否能回答它。

• 做成 ticket 当 问题已经清晰 —— 即使它被阻塞，你尚不能行动。
• 尚未明确当 你还无法如此精确地表述它。不要将迷雾预先切成 ticket 大小的碎片：它比 ticket 更粗糙，一个补丁可能在当前沿到达时升级为多个 tickets，或零个。

尚未明确排除已决策的内容（Decisions so far）、已有的活跃 ticket 以及超出范围的内容（下一节）。

超出范围

迷雾只会向目标方向聚集。目标确定了范围，因此目标之外的工作是超出范围的 —— 它不是迷雾，也不属于尚未明确。它在地图上拥有自己的超出范围章节：你已自觉排除在此工作之外的工作。是范围而非清晰度让它落入此处。

超出范围的工作永不升级 —— 前沿停在目标处 —— 因此只有在目标被重新划定后才会重新考虑，且以一个全新的工作而非恢复旧工作的形式出现。

将某物裁定为超出范围是一个范围界定行为，而非路径上的一步。当已有的一个 ticket 被发现位于目标之外 —— 绘制地图时范围划分错误，或因某个解决方案而暴露 —— 关闭它（一个已关闭的 ticket 明确地不在前沿上），并在超出范围章节留下一行：概括加上为何超出范围，链接已关闭的 ticket。它不会出现在已做出的决策中，该节记录实际走过的路径 —— 范围边界不是路径上的一步。

调用方式

两种模式。无论哪种，每个会话绝不解决超过一个 ticket。

绘制地图

用户带着模糊的想法调用。

1. 命名目标。 运行一次 /grilling 和 /domain-modeling 会话，以确定此地图正在寻路的目标 —— spec、决策或变更。目标确定了范围，因此先确定它。
2. 绘制前沿。 再次质询，这次广度优先：在整个空间上扩展而非深入任何一条线索，揭示开放的决策和现在可以迈出的第一步。如果此过程没有浮现任何迷雾 —— 通往目标的路径已经清晰，整个旅程足够小到放入一个会话 —— 你不需要地图。停下来询问用户他们希望如何继续。
3. 创建地图（标签 wayfinder:map）：填写 Destination 和 Notes，Decisions so-far 为空，迷雾草拟进尚未明确。
4. 创建你现在能明确的 tickets 作为地图的子 issues —— 然后在第二遍中连接阻塞边（issues 需要首先有 ID 才能相互引用）。连接关系将它们排序为前沿和被阻塞；你尚无法明确的都在迷雾中 —— 尚未明确章节。
5. 停止 —— 绘制地图是一个会话的工作；不要同时解决 tickets。

遍历地图

用户带着一张地图（URL 或编号）调用。Ticket 是可选的 —— 不提供时，你选择下一个决策，而非用户。

1. 加载地图 —— 低分辨率视图，而非每个 ticket 的正文。
2. 选择 ticket。如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket。领取它：在任何工作之前将它分配给你自己。
3. 解决它 —— 按需缩放：按需拉取任何相关或已关闭 ticket 的完整正文；调用 ## Notes 块中指定的技能。如有疑问，使用 /grilling 和 /domain-modeling。
4. 记录解决方案：发布答案作为解决方案评论，关闭 issue，并在地图的 Decisions-so-far 中追加一条上下文指针。
5. 添加新浮现的 tickets（先创建再连接）；升级答案使任何变得可明确的迷雾，从尚未明确中清除每个已升级的补丁，使其仅以其新 ticket 的形式存在。如果答案揭示某个 ticket —— 这个或其他 —— 位于目标之外，将其裁定为超出范围而非在路径上解决它。如果该决策使地图的其他部分无效，更新或删除这些 tickets。

用户可以并行运行未被阻塞的 tickets，因此需预期其他会话会并发编辑 tracker。