Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

wayfinder

把一大块工作——超出单个 agent 会话所能容纳的量——规划为工单跟踪器上一张由决策工单构成的共享地图,逐个解决它们,直到通往目的地的路径变得清晰。

WenWuZhiDao · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add WenWuZhiDao/mattpocock-skills-zh --skill wayfinder

About this skill


name: wayfinder description: 把一大块工作——超出单个 agent 会话所能容纳的量——规划为工单跟踪器上一张由决策工单构成的共享地图,逐个解决它们,直到通往目的地的路径变得清晰。 disable-model-invocation: true

一个松散的想法到来了——大到一个 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 清掉,让它只作为它的新工单存在。如果答案揭示某个工单——这一个或另一个——坐落在目的地之外,就把它判为范围之外,而不是在路线上解决它。如果这个决策使地图的其他部分失效,就更新或删除那些工单。

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