AGENT SKILL

wayfinder

把一大块工作(超过一个 agent 会话能装下的)规划为 issue 跟踪器上一张由决策 ticket 构成的共享地图,然后一次解决一个,直到通往目的地的路清晰可见。

License 许可
MIT
所属仓库
muscaestar/skills
最近更新
2026-10-19
Stars
★ 0
Forks
0

01 前言 Front Matter

name
wayfinder
description
把一大块工作(超过一个 agent 会话能装下的)规划为 issue 跟踪器上一张由决策 ticket 构成的共享地图,然后一次解决一个,直到通往目的地的路清晰可见。
commit_version
8295b8e10d4cdb6cce772a56dda7b7c37075074d
disable-model-invocation
true

02 资源文件 1

03 SKILL.md 正文

一个模糊的想法出现了,太大,一个 agent 会话装不下,而且笼罩在迷雾中:从这里到目的地的路还看不见。Wayfinding 是关于找到那条路,而不是朝目的地猛冲。本技能把这条路绘制成仓库 issue 跟踪器上的一张共享地图,然后一次一个地处理它的决策 ticket(解决结果是一个决定的问题,而不是要执行的构建切片),直到路线清晰。

目的地因每项工作而异,而命名它是绘制地图的第一个动作,它塑造每一个 ticket。它可能是一份要交接并迭代的规格、一个要在规划开始前敲定的决定,或一次就地完成的改动(比如数据结构迁移)。地图是领域无关的:工程工作、课程内容,任何符合这个形状的东西都行。

规划,而不是执行

Wayfinder 默认是规划:每个 ticket 解决一个决策,当路清晰时地图就完成了:在有人去真正做那件事之前,没有剩下要决定的东西。想要直接动手做的冲动,通常就是你已经到达地图边缘、该交接了的信号。一项工作可以在它的 Notes 中覆盖这一点(把执行带进地图本身),但如果没有这样的覆盖,就产出决定,而不是交付物。

用名字称呼

每张地图和每个 ticket 都是一个 issue,所以它有一个名字:它的标题。在一切人类会读到的内容中(叙述、地图的 Decisions-so-far),用那个名字称呼它,永远不要用光秃秃的 id、编号或 slug。一墙 #42, #43, #44 是没法读的;名字一目了然。id 和 URL 不会消失(名字包裹着它的链接),但它们待在名字_内部_,永远不代表名字本身。

地图

地图是本仓库 issue 跟踪器上的单个 issue,带 wayfinder:map 标签,它是权威制品。它的 ticket 是地图的子 issue。

地图是索引,不是仓库。它列出已做出的决定,并指向保存其细节的 ticket;一个决定恰好只存在于一个地方(它的 ticket),所以地图从不复述它,只做摘要并链接。

地图、它的子 ticket、阻塞和 frontier 查询在物理上存放在哪里,是因跟踪器而异的。 issue 跟踪器应该已经提供给你了。如果没有,告诉用户运行 /setup-matt-pocock-skills。查阅跟踪器文档的 "Wayfinding operations" 小节,了解_本_仓库如何表达它们。如果没有提供跟踪器,默认使用本地 markdown 跟踪器。

地图正文

整张地图的低分辨率视图,每个会话加载一次。未关闭的 ticket不列出:它们是未关闭的子 issue,通过查询找到。

## Destination

<到达这张地图终点是什么样子,即这项工作正在寻找通往它的路的那个规格、决定或改动。一两行;每个会话在选择 ticket 之前先以此定向。>

## Notes

<领域;每个会话都应查阅的技能;这项工作的长期偏好>

## Decisions so far

<!-- 索引:每个已关闭 ticket 一行:足以判断相关性,然后放大链接去看 ticket 保存的细节 -->

- [<closed ticket title>](link) — <答案的一句话摘要>

## Not yet specified

<!-- 见"战争迷雾":还无法做成 ticket 的在范围内迷雾;随 frontier 推进而毕业 -->

## Out of scope

<!-- 见"超出范围":被判定在目的地之外的工作;已关闭,永不毕业 -->

Ticket

每个 ticket 是地图的一个子 issue;跟踪器的 issue id 就是它的身份。它的正文是那个问题,大小以一个 100K token 的 agent 会话为准:

## Question

<这个 ticket 要解决的决策或调查>

每个 ticket 携带一个 wayfinder:<type> 标签:research、prototype、grilling、task 之一(见 Ticket 类型)。wayfinder: 标签是地图及其 ticket 携带的唯一标签,绝不挂 ready-for-agent 之类的 triage 标签:它们是决策,不是实现工作。

会话通过把 ticket 指派给驱动地图的开发者来认领它,最先做,在任何工作之前,这样并发会话会跳过它。那个指派人_就是_认领:一个未关闭、未指派的 ticket 就是未认领的。

阻塞使用跟踪器的原生依赖关系,这很关键,因为它能在跟踪器自己的 UI 中_可视化地_呈现 frontier,让人类不用打开地图就能看到什么可以拿。只有缺乏原生阻塞的跟踪器才退回正文约定。当阻塞一个 ticket 的所有 ticket 都关闭时,它就是未阻塞的;frontier 是那些未关闭、未阻塞、未认领的子 ticket,即已知的边缘。

答案不属于正文:它在解决时记录(见走遍地图)。解决 ticket 过程中产出的资产从 issue 上链接,而不是粘贴进去。

Ticket 类型

每个 ticket 要么是 HITL(人类在环中,与为自己发言的人类_一起_处理),要么是 AFK,由 agent 单独驱动。HITL ticket 只能通过那种实时交流来解决;agent 永远代替不了人类的那一方(一个自问自答的 grilling agent 就破坏了这一点)。

  • Research(AFK):阅读文档、第三方 API 或本地资源(如知识库),浮现某个决策所等待的事实。由调用 Skill 工具并传入 "research" 的子 agent 解决。当需要当前工作目录之外的知识时使用。
  • Prototype(HITL):通过做一个便宜、粗糙、具体、可供评头论足的制品来提高讨论的保真度:一个大纲、一个粗略的尝试、一个 stub,或 UI/逻辑代码,通过调用 Skill 工具并传入 "prototype" 完成。把原型链接为资产。当"它应该长什么样"或"它应该怎么表现"是关键问题时使用。
  • Grilling(HITL):对话。默认情况。始终调用 Skill 工具两次,分别传入 "grilling" 和 "domain-modeling"。
  • Task(HITL 或 AFK):在做出某个_决定_之前必须完成的手工工作:没有什么要决定、原型或研究的,但在它完成之前讨论被卡住。注册一个服务以便评估它的 API、开通访问权限、移动数据以便看清它的形状。这是唯一一个_动手做_而不是做决定的类型:它赢得自己位置的方式是解锁一个决策,而不是交付目的地。agent 能单独驱动就单独驱动(AFK);否则交给人类一份精确的清单(HITL)。工作完成即解决;答案记录做了什么以及后续 ticket 依赖的任何事实(凭据位置、新 URL、行数)。

战争迷雾

地图是_刻意_不完整的:不要绘制你还看不见的东西。在活跃 ticket 之外是战争迷雾,即对那些你能感觉到正在逼近、但还无法确定的决策和调查的朦胧视野,因为它们悬在仍未解决的问题上。解决一个 ticket 会清除它前方的迷雾,让现在可以说清楚的东西毕业成为新的 ticket,一次一个,直到通往目的地的路清晰、再没有 ticket 剩余。

地图的 Not yet specified 小节就是那个朦胧视野被写下来的地方:疑似的问题、以后要重访的区域。它是朝向目的地的未发现 frontier:这里的一切都在范围内,只是还不够清晰、无法做成 ticket。视野允许多宽松就写多宽松、多完整就写多完整;它同时充当协作者了解这项工作走向的路标。

迷雾还是 ticket? 检验标准是你现在能否精确陈述那个问题,而_不是_你能否现在回答它。

  • 当问题已经足够清晰时做成ticket,即使它被阻塞、你还无法行动。
  • 当你还无法把它表述得那么清晰时放进 Not yet specified。不要把迷雾预先切成 ticket 大小的块:它比 ticket 粗,而且当 frontier 抵达时,一片迷雾可能毕业成好几个 ticket,也可能一个都没有。

Not yet specified 排除已决定的事(Decisions so far)、已是活跃 ticket 的事,以及超出范围的事(下一节)。

超出范围

迷雾只朝目的地方向聚集。目的地固定了范围,所以超出它的工作是超出范围的:它不是迷雾,也不属于 Not yet specified。它在地图上有自己的 Out of scope 小节:你有意识地排除在_这_项工作之外的东西。让它落在这里的是范围,不是清晰度。

超出范围的工作永不毕业(frontier 在目的地处停止),所以它只有在目的地被重新绘制时才会回来,而且那时是作为一项全新的工作,而不是恢复。

把某件事判定为超出范围是一个定界行为,不是路线上的一步。当一个已存在的 ticket 被发现位于目的地之外(绘制时被错误地圈进了范围,或被某个解决暴露出来),关闭它(关闭的 ticket 明确地离开 frontier),并在 Out of scope 小节留一行:摘要加为什么超出范围,链接到已关闭的 ticket。它留在 Decisions so far 之外,因为后者记录的是实际走过的路线:范围边界不是路线上的一步。

调用方式

两种模式。无论哪种,每个会话解决的 ticket 永远不要超过一个,research ticket 除外。

绘制地图

用户带着一个模糊的想法调用。

  1. 命名目的地。 调用 Skill 工具两次,分别传入 "grilling" 和 "domain-modeling",确定这张地图在寻找通往什么的路:那个规格、决定或改动。目的地固定范围,所以它最先敲定。
  2. 绘制 frontier。 再次 grill,这次是广度优先:在整个空间上扇形展开,而不是在任何一条线上深入,浮现未决的决策和现在就能迈出的第一步。如果这没有浮现任何迷雾(通往目的地的路已经清晰,整段旅程小到一个会话就够),你不需要地图。停下来问用户想怎么继续。
  3. 创建地图(标签 wayfinder:map):填好 Destination 和 Notes,Decisions-so-far 留空,迷雾草图写进 Not yet specified。
  4. 创建你现在就能说清楚的 ticket,作为地图的子 issue,然后在第二遍中接好阻塞边(issue 需要先获得 id 才能互相引用)。交叉引用也在这一遍里用真实 id 写好:占位符 #<n> 会自动链接到无关的 issue。接线把它们分拣进 frontier 和被阻塞的两堆;你尚且无法说清楚的一切都留在迷雾里,即 Not yet specified 小节。
  5. 发射 research 子 agent。 对你刚创建的每个 research ticket,启动一个调用 Skill 工具并传入 "research" 的子 agent 来并行解决它,把发现捕获到一个一次性的 research/<name> 分支上,并从 ticket 留下上下文指针。推送分支,但不开 PR:它永远不会被合并。
  6. 停下:绘制就是一个会话的工作;它不亲手解决任何东西。

走遍地图

用户带着一张地图(URL 或编号)调用。ticket 是可选的:没有指定时,由你来挑下一个决策,而不是用户。

  1. 加载地图:低分辨率视图,而不是每个 ticket 的正文。
  2. 选择 ticket。如果用户点名了一个,用它。否则按顺序取第一个 frontier ticket。认领它:在任何工作之前把它指派给自己。
  3. 按它的 wayfinder:<type> 标签所命名的类型解决它(见 Ticket 类型)。读标签,不要只读正文:正文从不说明类型。按需放大:按需获取任何相关或已关闭 ticket 的完整正文;调用 Skill 工具并传入 ## Notes 块点名的技能。拿不准时,调用 Skill 工具两次,分别传入 "grilling" 和 "domain-modeling"。
  4. 记录解决方案:把答案发布为一条解决评论,关闭 issue,并向地图的 Decisions-so-far 追加上下文指针。
  5. 添加新浮现的 ticket(先创建后接线);让答案已能说清楚的迷雾毕业,把每片毕业的迷雾从 Not yet specified 中清除,让它只以新 ticket 的形式存在。如果答案揭示某个 ticket(这一个或另一个)位于目的地之外,把它判定为超出范围,而不是在路线上解决它。如果这个决定使地图的其他部分失效,更新或删除那些 ticket。

用户可能会并行处理未阻塞的 ticket,所以要预期其他会话正在并发编辑跟踪器。

04 同仓库更多 Skills