wayfinder

一个模糊的想法出现了，它规模太大，无法在一次 Agent 会话中完成，并且笼罩在迷雾中：从这里通往 目的地 的路径尚不可见。Wayfinding 的重点是找到这条路，而不是直接冲向目的地。本技能将这条路绘制为代码仓库议题跟踪器上的一份共享地图，然后逐一处理其中的决策工单（这类问题的解决结果是一项决定，而不是需要执行的构建切片），直到路线清晰。

目的地因项目而异，而命名目的地是绘图的第一步，它会影响每一张工单。目的地可能是一份需要交接并持续迭代的规格说明，可能是一项需要在规划开始前锁定的决定，也可能是一次原地进行的变更，例如数据结构迁移。该地图与领域无关：工程工作、课程内容或其他符合此结构的内容都适用。

规划，而非执行

Wayfinder 默认进行规划：每张工单解决一项决定，当路线清晰、无需再做决定即可由人去执行时，地图即告完成。想直接动手做的冲动通常说明已经到达地图的边缘，是时候交接了。项目可以在其备注中覆盖这一默认设定，将执行纳入地图本身，但在没有此类说明时，只产出决定，而不产出交付物。

按名称引用

每份地图和每张工单都是一个议题，因此都有一个名称，即其标题。在所有供人阅读的内容中（叙述文字、地图的「已做决定」部分），都应使用该名称来引用，绝不要只用裸 id、编号或 slug。满屏的 #42, #43, #44 难以辨认，名称一眼即可读懂。id 和 URL 并不会消失：名称包裹其链接，但二者都位于名称_之内_，不能取代名称。

地图

地图是这个仓库议题跟踪器上的单个议题，带有 wayfinder:map 标签，是权威的产物。它的工单是该地图的子议题。

地图是索引，而不是存储。它列出已做出的决定，并指向承载其详细内容的工单；每项决定只存在于一个地方，即其工单中，因此地图从不重复陈述决定，只做概括并附上链接。

地图、其子工单、阻塞关系以及前沿查询在跟踪器中的具体存放方式因跟踪器而异。 议题跟踪器应当已经提供给你。如果没有，请告知用户运行 /setup-matt-pocock-skills。请查阅跟踪器文档中的「Wayfinding 操作」章节，了解_本仓库_如何表达这些内容。如果没有提供任何跟踪器，则默认使用本地 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 之类的分类标签：它们是决定，而不是实现工作。

会话在开始任何工作之前，首先将工单分配给驱动该地图的开发者，以此认领该工单，从而使并发会话跳过它。这个负责人_就是_认领记录：未关闭且未分配的工单即为未认领。

阻塞关系使用跟踪器的原生依赖关系。这一点至关重要，因为它能在跟踪器自身的 UI 中_直观地_呈现前沿，让人无需打开地图就能看到哪些工单可以着手处理。只有缺少原生阻塞功能的跟踪器，才退而使用正文约定。当阻塞该工单的所有工单都已关闭时，该工单即为未阻塞；前沿则是未关闭、未阻塞且未认领的子工单，也就是已知范围的边缘。

答案不属于正文内容，而是在解决工单时记录下来（参见逐个处理地图）。解决工单时创建的资产应从议题中链接，而不是直接粘贴进来。

工单类型

每个工单要么是 HITL（human in the loop，与人类一起完成，由人类本人发表意见），要么是 AFK，完全由 Agent 独自推进。HITL 工单只能通过这种实时交流来解决；Agent 不能代替人类一方发言（一个自己回答自己问题的 grilling Agent 就违反了这一点）。

• Research（AFK）：阅读文档、第三方 API 或知识库等本地资源，以找出某个决策所依赖的事实。由子代理调用 Skill tool 并传入 "research" 来完成。当需要当前工作目录之外的知识时使用。
• Prototype（HITL）：通过制作一个低成本、粗略但具体的产出物（大纲、粗略方案、桩代码，或 UI/逻辑代码）来提高讨论的保真度，供各方评审。调用 Skill tool 并传入 "prototype" 来完成。将原型作为资产进行链接。当关键问题是"应该长什么样"或"应该如何运作"时使用。
• Grilling（HITL）：对话。这是默认情况。必须调用两次 Skill tool，分别传入 "grilling" 和 "domain-modeling"。
• Task（HITL 或 AFK）：在做出_决策_之前必须完成的手动工作：没有需要决定、制作原型或调研的内容，但讨论在其完成之前无法推进。例如注册某项服务以便评估其 API、开通访问权限、迁移数据以便查看其结构。这是唯一_执行_而非决策的类型，其价值在于解除某个决策的阻塞，而不是交付最终目标。Agent 能独自完成时由其推进（AFK）；否则将精确的清单交给人类（HITL）。完成工作后即视为解决；结果需记录已完成的操作以及后续工单所依赖的结果性事实（如凭据位置、新 URL、行数）。

战争迷雾

地图_有意_保持不完整：不要绘制你还看不清的部分。在现有工单之外，是战争迷雾：对那些你能察觉即将出现、但目前无法明确界定的决策与调查的模糊视图，因为它们依赖于仍未解决的问题。解决一个工单会清除其前方的迷雾，并将现已可明确界定的内容逐一转化为新工单，直到通往目标的路径清晰、不再有遗留工单为止。

地图中的尚未明确部分用于记录这种模糊视图：疑似的问题与之后需要重新审视的区域。它是通往目标的未探索前沿：其中的一切都在范围之内，只是还不够清晰，无法立为工单。可以按视图允许的程度或详或略地书写；它同时也是供协作者了解工作方向的路标。

迷雾还是工单？ 判断标准是你现在能否精确地陈述这个问题，_而不是_你现在能否回答它。

• 当问题已经明确时立为工单，即使它被阻塞、暂时无法行动。
• 当你还无法如此精确地表述时，列入尚未明确。不要把迷雾预先切分成工单大小的片段：它比工单更粗略，一个条目在前沿抵达时可能转化为多个工单，也可能一个都不转化。

尚未明确不包括已决定的内容（已做出的决策）、已存在的现行工单，以及超出范围的内容（下一节）。

范围外

迷雾只会朝着目的地方向聚集。目的地决定范围，因此超出范围的工作不是迷雾，也不属于尚未明确。它应在地图上拥有单独的范围外部分：即你有意为_本次_工作排除在外的工作。是范围而非清晰度把它归入此处。

范围外的工作永远不会升级（前沿止于目的地），因此只有在目的地被重新划定时才会回到地图中，且是作为全新的工作，而非延续之前的工作。

将某事排除在范围外是一种范围界定行为，而不是路线上的一步。当一个已存在的工单结果超出目的地时（在规划时被错误纳入，或因某次解决而暴露出来），关闭它（已关闭的工单明确不在前沿上），并在范围外部分留下一行：概要加上超出范围的原因，并链接到已关闭的工单。它不进入已做决定，该部分记录的是实际走过的路线；范围边界不是路线上的一步。

调用方式

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

绘制地图

用户以模糊的想法发起调用。

1. 确定目的地。 分别调用 Skill 工具两次，参数为 "grilling" 和 "domain-modeling"，以明确此地图要抵达的目标：规格、决策或变更。目的地决定范围，因此需先确定。
2. 勾勒前沿。 再次进行追问，这次采用广度优先：横向覆盖整个空间，而非深入某一条线索，找出待定决策以及现在就能着手的第一步。如果这一步没有发现任何迷雾（通往目的地的道路已经清晰，整个旅程小到一次会话即可完成），则无需地图。停下来询问用户希望如何继续。
3. 创建地图（标签 wayfinder:map）：填写目的地和笔记，已做决定留空，并将迷雾概略写入尚未明确中。
4. 为你现在能明确的工作创建工单，作为地图的子 issue；然后在第二轮中连接阻塞关系（issue 需要先有 id 才能相互引用）。同一轮中也要写入交叉引用，并使用真实 id：占位符 #<n> 会自动链接到无关的 issue。连线会将工单分入前沿与受阻两类；所有无法立即明确的工作仍留在迷雾中，即尚未明确部分。
5. 启动研究子代理。 对于你刚创建的每个 research 工单，启动一个子代理，调用 Skill 工具并传入 "research" 以并行解决该工单，将其发现记录在一次性的 research/<name> 分支上，并附带工单中的上下文指针。推送该分支但不开 PR：它永远不会被合并。
6. 停止：绘制地图是一次会话的工作，它本身不解决任何工单。

按地图推进工作

用户通过地图（URL 或编号）调用。工单是可选的：未指定工单时，由你而不是用户来选择下一项决策。

1. 加载地图：查看低分辨率视图，而不是每个工单的完整正文。
2. 选择工单。如果用户指定了工单，就使用该工单。否则按顺序取第一个前沿工单。认领它：在开始任何工作前将其分配给你自己。
3. 按其 wayfinder:<type> 标签所示的类型解决工单（参见 工单类型）。请阅读标签，而不仅是正文：正文从不声明类型。按需放大：随时获取任何相关或已关闭工单的完整正文；对 ## Notes 块中提到的每个技能，调用 Skill 工具。如有疑问，调用两次 Skill 工具，分别用于 "grilling" 和 "domain-modeling"。
4. 记录解决结果：以解决说明评论的形式发布答案，关闭 issue，并将上下文指针追加到地图的已做决策中。
5. 添加新浮现的工单（先创建再关联）；对于答案已使其可以明确说明的迷雾，将其转为具体工单，并从尚未明确中删除该已转化的条目，使其只存在于新工单中。如果答案显示某个工单（本工单或其他工单）位于目的地之外，则将其排除在范围之外，而不是在路线上解决它。如果该决策使地图的其他部分失效，则更新或删除相关工单。

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