wayfinder

一个松散的想法出现了，它太大，无法在一次 Agent 会话中完成，而且笼罩在迷雾中：从这里到目的地的路还看不清。寻路的目标是找到这条路，而不是径直冲向目的地。此技能会在仓库的问题跟踪器上绘制一张共享地图，然后逐一处理其中的决策工单（其解决方案是作出决策，而非可执行的构建任务切片），直到路线清晰。

不同工作项的目的地各不相同，绘制地图的第一步就是为它命名：这个名称会影响每张工单。目的地可能是一份要交接并迭代完善的规范、一项必须在开始规划前敲定的决策，或一项就地完成的变更，例如数据结构迁移。这张地图与领域无关：工程工作、课程内容，凡是符合这种形式的工作都可以。

规划，而非执行

Wayfinder 默认用于规划：每张工单解决一项决策；当路线清晰，且在有人开始执行之前已无待决事项时，地图就算完成。想直接动手做事的冲动，通常表明你已到达地图的边界，是时候交接了。某项工作可以在其备注中覆盖这一默认设置，将执行工作也纳入地图；但若没有这样的说明，就只产出决策，而非交付成果。

按名称引用

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

地图

地图是此仓库问题跟踪器上的一个单独问题，标记为 wayfinder:map，也是权威产物。地图的工单是其子问题。

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

地图、其子工单、阻塞关系以及前沿查询的实际存放位置取决于跟踪器。 问题跟踪器应该已提供给你。如果没有，请告知用户运行 /setup-matt-pocock-skills。请查阅跟踪器文档中的“寻路操作”部分，了解_此_仓库如何表达这些内容。如果未提供问题跟踪器，则默认使用本地 Markdown 跟踪器。

地图正文

低分辨率下的完整地图，每个会话加载一次。未结工单不会列出：它们是未结的子问题，通过查询找到。

## 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

工单

每个工单都是地图的一个子议题；追踪器的议题 ID 就是它的标识。工单正文是一个问题，范围适合在一次 100K token 的 Agent 会话中处理：

## Question

<the decision or investigation this ticket resolves>

每个工单都带有一个 wayfinder:<type> 标签，可选值为 research、prototype、grilling、task（参见工单类型）。wayfinder: 标签是地图及其工单唯一使用的标签，绝不会使用 ready-for-agent 这类分诊标签：它们代表决策，而不是实现工作。

会话持有认领时，还会使用另一个标签 in-progress（见下文的循环）。它是认领标记，不是分诊标签。

会话通过将工单指派给负责推进地图的开发者来认领工单；必须在任何工作开始之前完成，这样并发会话才会跳过该工单。被指派人_就是_认领者：未关闭且未指派的工单即为未认领。

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

• 相关：如果某个地图或工单有意依赖另一个事项的结果，但并未被其阻塞，请在正文中声明：“Related: #n (why)”。原因由掌握相关背景的会话记录一次，之后绝不推断补写。

答案不属于正文；它会在解决工单时记录（见通过地图开展工作）。解决工单时创建的资源应作为链接附在议题中，而不是直接粘贴进去。

工单类型

每个工单要么是 HITL（人在回路中，与能代表自己发言的人共同完成），要么是由 Agent 独自推进的 AFK。HITL 工单只能通过实时交流来解决；Agent 绝不会代替人类完成对方那一侧的交流（如果负责提问的 Agent 自己回答自己的问题，那就违背了这一原则）。

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

战争迷雾

地图是_刻意_不完整的：不要绘制你还看不到的内容。实时工单之外，是战争迷雾：你能看出即将到来的决策和调查，却还无法明确界定，因为它们取决于仍未解决的问题。解决一个工单，就会拨开它前方的迷雾，将现在可以明确界定的内容逐一转化为新工单，直到通往目的地的道路清晰，不再有工单为止。

地图中的尚未明确部分，就是记录这片朦胧视野的地方：可能存在的问题、之后需要重新审视的领域。这是通往目的地的未知前沿：这里的所有内容都在范围之内，只是还不够明确，无法成为工单。根据当前视野，尽量宽泛或详尽地记录；它也能为查看项目进展方向的协作者指引方向。

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

• **符合以下情况时建工单：**问题已经明确，即便它受阻、暂时无法处理。
• **符合以下情况时标记为尚未明确：**你还无法准确地表述问题。不要预先把迷雾切分成工单大小的块：它的粒度比工单更粗，前沿抵达时，一块内容可能转化为多个工单，也可能不转化为任何工单。

尚未明确不包括已经决定的事项（迄今为止的决策）、已有的实时工单，以及超出范围的事项（见下一节）。

超出范围

迷雾只会朝着目的地聚集。目的地界定了范围，因此超出目的地的工作超出范围：它不是迷雾，也不属于尚未明确。地图会为它单设一个超出范围部分，记录你有意排除在_本次_工作之外的事项。是否属于范围，而非是否明确，决定了事项是否归入此处。

超出范围的工作永远不会转化为工单（前沿止于目的地），因此只有在重新划定目的地时才会重新纳入，并且届时它会作为一项新的工作启动，而非恢复原有工作。

将某事项排除在范围之外是一项范围界定行为，而非路线上的一步。如果发现已有工单位于目的地之外（绘制地图时误纳入，或在解决其他事项时发现），请关闭该工单（已关闭的工单明确不属于前沿），并在超出范围部分留下一行说明：简述事项及其超出范围的原因，并链接到已关闭的工单。它不属于迄今为止的决策，因为该部分记录的是实际走过的路线；范围边界并非路线上的一步。

调用

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

绘制地图

用户以一个宽泛的想法发起请求。

1. 确定目的地。 调用两次 Skill 工具，分别使用“grilling”和“domain-modeling”，明确这张地图要找到什么：规范、决策或变更。先确定目的地，以此界定范围。
2. 绘制前沿。 再次进行 grilling，这次采用广度优先的方式：拓展至整个空间，而不是深入某一条线索，找出尚未作出的决策，以及现在可以采取的第一步。如果没有发现迷雾（通往目的地的路径已经清楚，整个过程也足够小，可以在一次会话中完成），就不必绘制地图。停止，并询问用户希望如何继续。
3. 创建地图（标记为 wayfinder:map）：填写 Destination 和 Notes，将 Decisions-so-far 留空，并把迷雾简要列入 Not yet specified。
4. 创建现在可以明确说明的工单，将其设为地图的子议题，然后在第二轮添加阻塞关系（议题需要先有 id，才能相互引用）。这一轮也要填写交叉引用，并使用真实 id：占位符 #<n> 会自动链接到无关议题。添加关系会将工单归入前沿或被阻塞项；所有尚无法明确说明的内容仍留在迷雾中，即 Not yet specified 部分。
5. 启动研究子 Agent。 对刚创建的每个 research 工单，启动一个子 Agent，让它调用 Skill 工具并使用“research”并行解决问题；在临时的 research/<name> 分支上记录研究结果，并附上来自工单的上下文指针。推送分支，但不要创建 PR：该分支永远不会合并。
6. 停止：绘制地图是一项单次会话的工作，不解决任何问题。

按地图推进工作

用户使用一张地图发起请求（URL 或编号）。工单是可选的：如果没有指定工单，由你而非用户选择下一个决策。

1. 加载地图：查看低分辨率视图，而非每张工单的正文。
2. 选择工单。如果用户指定了工单，就使用该工单；否则，按顺序选择前沿中的第一个工单。认领它：开始任何工作前，将工单指派给自己，并添加 in-progress 标签。
3. 按 wayfinder:<type> 标签所指明的类型解决工单（参见工单类型）。读取标签，而不只是正文：正文不会说明类型。按需深入查看：需要时获取相关或已关闭工单的完整正文；调用 ## Notes 区块中所列技能对应的 Skill 工具。如有疑问，调用两次 Skill 工具，分别使用“grilling”和“domain-modeling”。
4. 记录解决结果：以解决评论的形式发布答案，关闭议题并移除其 in-progress 标签，然后在地图的 Decisions-so-far 中追加上下文指针。
5. 添加新发现的工单（先创建，再添加关系）；如果答案让迷雾中的内容变得可以明确说明，就将其转化为工单，并从 Not yet specified 中清除每个已转化的部分，使其只保留在新工单中。如果答案表明某个工单（当前工单或其他工单）不属于目的地范围，将其排除在范围之外，而不是在推进路径上解决它。如果某个决策使地图的其他部分失效，就更新或删除相应工单。

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