wayfinder

一个松散的想法到来了——大到一个 agent 会话装不下，而且裹在迷雾里：从此处到目的地的路径尚不可见。寻路（Wayfinding）关乎找到那条路，而不是朝目的地猛冲。这个技能把路径绘制成仓库工单跟踪器上的一张共享地图，然后逐个处理它的决策工单——那些其解决就是一个决策（而非要执行的构建切片）的问题——直到路线清晰。

目的地因工作而异，而给它命名是绘图的第一个动作——它塑造了每一个工单。它可能是一份要交接并迭代的规格、一个在规划开始前要锁定的决策，或者一个就地做出的改动（如数据结构迁移）。这张地图是领域无关的——工程工作、课程内容，只要合乎这个形状都行。

规划，不做执行

Wayfinder 默认是规划：每个工单解决一个决策，而当路径清晰时地图就完成了——在有人去把事情做出来之前，没有剩下什么要决定的了。想要直接去做那份工作的冲动，通常是你已经到了地图边缘、该交接的信号。一项工作可以在它的 Notes 里覆盖这一点——把执行也带进地图本身——但在没有这一点的情况下，产出决策，而非交付物。

按名字指代

每个地图和工单都是一个 issue，所以它有一个名字——它的标题。在人类会读到的一切里——旁白、地图的 Decisions-so-far——都用那个名字指代它，绝不用一个裸的 id、编号或 slug。一堵 #42, #43, #44 的墙是难以辨认的；名字一眼就能读懂。id 和 URL 不会消失——一个名字包着它的链接——但它们乘在名字内部，绝不替代名字。

地图

地图是本仓库工单跟踪器上的一个单一 issue，打了 wayfinder:map 标签——规范的产物。它的工单是地图的子 issue。

地图是一个索引，不是一个存储。它列出已做出的决策并指向持有其细节的工单；一个决策恰好活在一个地方——它的工单——所以地图从不复述它，只给它一个要点并链接过去。

地图、它的子工单、阻塞和前沿查询在物理上活在哪里，是跟踪器专属的。 工单跟踪器应当已经提供给你——如果没有，运行 /setup-matt-pocock-skills。查阅跟踪器文档的「寻路操作」一节，了解这个仓库如何表达它们。如果没有提供跟踪器，默认走本地 markdown 跟踪器。

地图正文

整张地图的低分辨率版，每个会话加载一次。未关闭的工单不列出——它们是未关闭的子 issue，靠查询找到。

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

<!-- the index — one line per closed ticket: enough to judge relevance, then zoom the link for the detail the ticket holds -->

- [<closed ticket title>](link) — <one-line gist of the answer>

## Not yet specified

<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->

## Out of scope

<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->

工单

每个工单都是地图的一个子 issue；跟踪器的 issue id 是它的身份。它的正文是那个问题，大小裁到一个 100K token 的 agent 会话：

## Question

<the decision or investigation this ticket resolves>

每个工单携带一个 wayfinder:<type> 标签——research、prototype、grilling、task 之一（见工单类型）。

一个会话通过把工单分配给推进地图的开发者来领取它，在任何工作之前这么做，好让并发的会话跳过它。那个 assignee 就是领取：一个未关闭、未分配的工单是未领取的。

阻塞使用跟踪器的原生依赖关系——这至关重要，因为它在跟踪器自己的 UI 里可视化地渲染前沿，所以人类不用打开地图就能看到什么是可取的。只有缺乏原生阻塞的跟踪器才回退到正文约定。当阻塞它的每个工单都被关闭时，一个工单就解除阻塞；前沿是那些未关闭、未阻塞、未领取的子工单——已知的边缘。

答案不是正文的一部分——它在解决时才被记录（见逐个走过地图）。解决一个工单时创建的资产从该 issue 链接过去，而不是粘贴进去。

工单类型

每个工单要么是 HITL——人在环中，与一个为自己发声的人一起处理——要么是 AFK，由 agent 独自推进。一个 HITL 工单只通过那次实时交流才能解决；agent 绝不替人类那一方发声（一个自问自答的拷问 agent 已经破坏了这一点）。

• Research（研究，AFK）：阅读文档、第三方 API，或知识库这样的本地资源，以浮现某个决策所等待的一个事实。由一个 /research 子 agent 解决。当需要当前工作目录之外的知识时使用。
• Prototype（原型，HITL）：通过制作一个便宜、粗糙、具体的、可供反应的产物——一份提纲、一个粗略的方案、一个桩，或通过 /prototype 技能做出的 UI/逻辑代码——来提高讨论的保真度。把原型作为资产链接过去。当「它该长什么样」或「它该如何表现」是关键问题时使用。
• Grilling（拷问，HITL）：对话。默认情形。始终调用 /grilling 和 /domain-modeling 技能。
• Task（任务，HITL 或 AFK）：在一个决策能被做出之前必须发生的手工工作——没有什么可决定、可原型、可研究的，但讨论在它完成之前被阻塞。注册一个服务好让它的 API 能被评判、配置访问权限、移动数据好让它的形状能被看到。这是唯一一个做而非决定的类型——而它凭借解除一个决策的阻塞、而非交付目的地，来赢得它的位置。agent 在能独自做的地方独自推进它（AFK）；否则它交给人类一份精确的清单（HITL）。工作完成时即解决；答案记录做了什么以及后续工单所依赖的任何由此产生的事实（凭据位置、新 URL、行数）。

战争迷雾

地图是刻意不完整的：别去绘制你还看不见的东西。在活跃工单之外躺着战争迷雾——那些你能感觉到即将到来、却还钉不下来的决策和调查的朦胧视野，因为它们悬于仍然未决的问题之上。解决一个工单会清除它前方的迷雾，把如今可规范化的东西毕业为新鲜的工单——一次一个，直到通往目的地的路径清晰、没有工单剩下。

地图的 Not yet specified 一节就是把那朦胧视野写下来的地方：可疑的问题、稍后要重访的区域。它是朝向目的地的未探索前沿——这里的一切都在范围内，只是还不够锐利到能开工单。视野允许多松就写多松、允许多满就写多满；它还兼作一块路标，供阅读这项工作去向的协作者参考。

迷雾还是工单？ 判据是你现在能否精确陈述这个问题——而不是你现在能否回答它。

• 开工单，当问题已经锐利——即便它被阻塞、你还不能对它行动。
• 归为 Not yet specified，当你还不能把它表述得那么锐利。别把迷雾预先切成工单大小的块：它比一个工单更粗，一块可能在前沿抵达它时毕业成若干工单，或者一个都不毕业。

Not yet specified 排除已经决定的（Decisions so far）、已经是一个活跃工单的，以及范围之外的（下一节）。

范围之外

迷雾只会朝向目的地聚集。目的地固定了范围，所以它之外的工作是范围之外——它不是迷雾，也不属于 Not yet specified。它在地图上有自己的 Out of scope 一节：你有意识地排除出这项工作的工作。是范围、而非锐利度，把它落到这里。

范围之外的工作从不毕业——前沿在目的地处停止——所以它只在目的地被重画时才返回，而且那时是作为一项新的工作，不是一次续接。

把某样东西判为范围之外是一个划定范围的动作，不是路线上的一步。当一个已经存在的工单结果坐落在目的地之外时——绘图时误纳入的，或被某次解决暴露的——关闭它（一个关闭的工单明确无疑地不在前沿上），并在 Out of scope 一节留一行：要点加上它为何在范围之外，链接那个关闭的工单。它不进 Decisions so far，后者记录的是实际走过的路线——一个范围边界不是它上面的一步。

调用

两种模式。无论哪种，每个会话绝不解决超过一个工单——研究工单例外。

绘制地图

用户带着一个松散的想法调用。

1. 给目的地命名。 运行一次 /grilling 和 /domain-modeling 会话，钉下这张地图在找路通往什么——那份规格、决策或改动。目的地固定了范围，所以它最先定夺。
2. 勘测前沿。 再拷问一次，这次广度优先：在整个空间里铺开，而不是在任何一条线上钻深，浮现出那些未决的决策和现在可迈出的第一步。如果这浮现不出迷雾——通往目的地的路径已经清晰，整段旅程小到一个会话就够——你不需要地图。停下并问用户他们想如何推进。
3. 创建地图（标签 wayfinder:map）：填好 Destination 和 Notes，Decisions-so-far 留空，把迷雾勾进 Not yet specified。
4. 创建你现在能规范化的工单，作为地图的子 issue——然后在第二遍里接上阻塞边（issue 得先有 id 才能互相引用）。接线把它们分拣进前沿和被阻塞的；你还不能规范化的一切留在迷雾里——Not yet specified 一节。
5. 发射研究子 agent。 对你刚创建的每个 research 工单，起一个 /research 子 agent 并行解决它，把它的发现捕获在一个用完即弃的 research/<name> 分支上，并从工单留一个上下文指针。
6. 停——绘图是一个会话的工作；它不亲手解决任何东西。

逐个走过地图

用户带着一张地图（URL 或编号）调用。工单是可选的——没有工单时，由你、而非用户来挑下一个决策。

1. 加载地图——那个低分辨率视图，而不是每一个工单正文。
2. 选择工单。如果用户点名了一个，就用它。否则按顺序取第一个前沿工单。领取它：在任何工作之前把它分配给你自己。
3. 解决它——按需缩放：按需获取任何相关或已关闭工单的完整正文；调用 ## Notes 块点名的那些技能。如有疑问，用 /grilling 和 /domain-modeling。
4. 记录解决：把答案作为一条解决评论发出，关闭该 issue，并向地图的 Decisions-so-far 追加一个上下文指针。
5. 添加新浮现的工单（先创建后接线）；毕业任何被答案变得可规范化的迷雾，把每一块已毕业的从 Not yet specified 清掉，让它只作为它的新工单存在。如果答案揭示某个工单——这一个或另一个——坐落在目的地之外，就把它判为范围之外，而不是在路线上解决它。如果这个决策使地图的其他部分失效，就更新或删除那些工单。

用户可能并行运行未阻塞的工单，所以要预料到其他会话在并发地编辑跟踪器。