Wayfinder 用于应对“一个模糊的想法已经出现，但大到单个智能体会话装不下、且路径被迷雾笼罩”的情形。它关注的是找到通往目的地的路，而不是直接冲向目的地。该技能把路线绘制成仓库问题追踪器上的共享地图，然后逐张处理其中的决策票据（即其解决结果是一个决策、而非待执行构建切片的疑问），直到路线清晰。
用途 目的地因具体工作而异，命名它是绘图的第一步，因为它会塑造每一张票据。它可能是一份待交接并迭代的规格、一个在规划开始前要锁定的决策，或一项就地完成的变更（如数据结构迁移）。地图与领域无关：工程工作、课程内容，凡符合该形态的皆可。
主要能力与原则
- 规划而非执行：默认每张票据解决一个决策；当路线清晰、在有人动手之前不再有待决事项时，地图即告完成。若产生“干脆直接做”的冲动，通常意味着已到达地图边缘、该交接了。个别工作可在 Notes 中覆盖此默认，把执行也纳入地图。
- 按名称引用：每张地图和票据都是一个 issue，其名称即标题。面向人类阅读的内容（叙述、地图的 Decisions-so-far）中一律用名称指代，不用裸 id、编号或 slug；id 与 URL 包在名称链接内，不替代名称。
- 地图即索引：地图是本仓库问题追踪器上带 wayfinder:map 标签的单个 issue，是权威产物；其票据是地图的子 issue。地图只列出已做决策并指向持有细节的票据，决策只存在于其票据一处，地图只做要点摘述与链接。
- 票据即问题：每张票据是地图的子 issue，追踪器 issue id 即其身份；正文即问题，规模约一个 10 万 token 的智能体会话。票据带 wayfinder:<type> 标签（research、prototype、grilling、task 之一），不携带 ready-for-agent 之类的分诊标签。会话通过把票据分配给自己来认领（认领先于任何工作），未分配即未认领。
- 阻塞与前沿：使用追踪器原生依赖关系表达阻塞，以便在追踪器自身 UI 中直观呈现前沿；仅在追踪器缺少原生阻塞时才退回正文约定。当阻塞它的所有票据都已关闭时该票据即解除阻塞；前沿是开放、未阻塞、未认领的子票据，即已知的边界。
票据类型 每张票据要么是 HITL（人在环中，与能自主表达的人类共同处理），要么是 AFK（由智能体独自主导）。HITL 票据只能通过实时交流解决，智能体不得代替人类一方（自我回答的拷问智能体即违反了这一点）。
- Research（AFK）：阅读文档、第三方 API 或本地知识库等资源，揭示某项决策所依赖的事实；通过调用 Skill 工具的 "research" 由子智能体解决；适用于需要当前工作目录之外的知识。
- Prototype（HITL）：制作廉价粗糙的具体产物（大纲、粗略方案、桩或 UI/逻辑代码）以提高讨论保真度，通过调用 Skill 工具的 "prototype" 完成，并把原型作为资产链接；适用于“它该长什么样”或“它该如何表现”是关键问题。
- Grilling（HITL）：对话，默认情形；始终调用 Skill 工具两次，分别为 "grilling" 和 "domain-modeling"。
- Task（HITL 或 AFK）：在决策之前必须完成的手工工作——无需决策、原型或研究，但讨论被它阻塞（如注册服务以便评判其 API、开通访问权限、移动数据以观察其形态）。这是唯一“做而非决定”的类型，其价值在于解锁决策而非交付目的地；能独自完成时由智能体 AFK 驱动，否则给人类一份精确清单（HITL）。完成后解决，答案记录做了什么及后续票据依赖的事实（凭据位置、新 URL、行数）。
迷雾与范围
- 战争迷雾（Fog of war）：地图刻意不完整，不绘制尚不可见之物。活跃票据之外是迷雾——你能察觉即将到来、但因仍开放的问题而无法确定的决策与调查。解决一张票据会清除其前方的迷雾，把如今可精确表述的内容逐张毕业为新的票据，直到通往目的地的路清晰、不再有票据。地图的 Not yet specified 部分记录这种朦胧视图（疑似问题、日后重访的区域），它属于范围内但尚不够清晰到可开票据；其粒度比票据粗，可能毕业为多张或零张票据。判断迷雾还是票据的标准是“现在能否精确陈述该问题”，而非“现在能否回答它”。
- 范围外（Out of scope）：目的地决定范围；超出目的地的工不属于迷雾，也不进 Not yet specified，而是单列 Out of scope，记录有意识排除的工作。范围外工作永不毕业，只有当目的地被重画时才以全新工作回归，而非续接。若某张已存在票据被发现位于目的地之外（绘图时误纳入或被解决结果暴露），则关闭它并在 Out of scope 记一行要点与原因并链接；它不进入记录实际走过路线的 Decisions so far。
使用方式 两种模式，任一模式下每会话最多解决一张票据（research 票据除外）。
- 绘制地图（用户以模糊想法发起）：先命名目的地，调用 "grilling" 与 "domain-modeling" 明确这张地图要通往什么（规格、决策或变更），目的地决定范围故先定；再广度优先地拷问，铺开整个空间而非深挖某一条线，浮现开放决策与当下可迈出的第一步。若未浮现迷雾（路线已清晰、整个旅程小到一次会话可完成），则无需地图，停止并询问用户如何继续。随后创建地图（wayfinder:map 标签），填好 Destination 与 Notes，Decisions-so-far 留空，把迷雾写进 Not yet specified；把现在可精确表述的票据创建为地图子 issue，再在第二遍中连好阻塞边与交叉引用（issue 需先有 id 才能互相引用，占位符 #<n> 会自动链接到无关 issue）。最后为每张 research 票据启动带全新上下文窗口的子智能体、调用 "research" 并行解决，把发现捕获到一次性 research/<name> 分支上，从票据给出上下文指针；推送分支但不开启 PR（此分支永不合并）。绘制是一次会话的工作，不亲手解决任何票据。
- 遍历地图（用户以地图 URL 或编号发起，票据可选；未指定时由你选下一个决策）：加载地图的低分辨率视图而非所有票据正文；若用户指定票据则用之，否则按顺序取前沿第一张，并在任何工作前先分配给自己认领。按 wayfinder:<type> 标签（而非正文，正文从不声明类型）解决，按需拉取相关或已关闭票据的完整正文，调用 ## Notes 中提及的技能；存疑时调用 "grilling" 与 "domain-modeling"。解决后把答案作为解决评论发布、关闭 issue，并在地图的 Decisions-so-far 追加上下文指针；创建新浮现的票据（先创建后连线），把因答案而可精确表述的迷雾毕业（同时从 Not yet specified 清除，使其只作为新票据存在）；若答案显示某票据位于目的地之外，则将其判为范围外而非在路线上解决；若决策使地图其它部分失效，则更新或删除相应票据。用户可能并行运行未阻塞票据，故需预期其他会话同时编辑追踪器。
存储与配置 地图、子票据、阻塞与前沿查询的物理位置因追踪器而异。问题追踪器应已提供给你；若未提供，告知用户运行 /setup-matt-pocock-skills，并查阅追踪器文档的 "Wayfinding operations" 章节了解本仓库如何表达这些操作；若仍未提供追踪器，默认使用本地 Markdown 追踪器。
适用场景与限制 适用于大范围、路径未知但需要持续推进的规划工作，领域不限。限制在于默认只产出决策不产出交付物（除非在 Notes 中显式覆盖）；每会话最多解决一张票据；HITL 票据必须有人类真实参与；需要依赖问题追踪器及其原生阻塞能力，追踪器缺失时需按上述流程配置或以本地 Markdown 兜底。