wayfinder

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

一个松散想法来了——对单次 agent 会话太大，而且裹在雾里：从这里到**目的地**的路还看不见。Wayfinding 是找出那条路，而不是冲向目的地。本 skill 把路画成仓库 issue tracker 上的**共享地图**，然后处理其**决策 tickets**——解决结果是一项决策的问题，而不是要执行的构建切片——一次一张，直到路线清晰。

目的地因每次努力而异，给它命名是绘图的第一动作——它塑造每一张 ticket。它可能是要交接并迭代的 spec、规划开始前要锁定的决策，或就地做出的变更如数据结构迁移。地图与领域无关——engineering 工作、课程内容，任何符合该形态的都行。

## 规划，不要去做

Wayfinder 默认是**规划**：每张 ticket 解决一项决策，当地图完成时路已清晰——在有人去做事之前没有剩下要决定的。想直接动手通常是信号：你已到达地图边缘，该交接了。一次努力可以在其 **Notes** 里覆盖这一点——把执行带进地图本身——但若没有，产出决策，而不是交付物。

## 按名称引用

每张地图和 ticket 都是一个 issue，所以它有一个**名称**——其标题。人类读到的一切——叙述、地图的 Decisions-so-far——都用该名称引用，绝不用光秃的 id、编号或 slug。一墙 `#42, #43, #44` 无法阅读；名称一眼可读。Id 和 URL 不会消失——名称包着其链接——但它们骑在名称*里面*，从不代替名称。

## 地图

地图是本仓库 issue tracker 上的单个 issue，打了 `wayfinder:map` 标签——规范产物。其 tickets 是地图的 child issues。

地图是**索引**，不是仓库。它列出已做出的决策，并指向持有细节的 tickets；一项决策只活在一个地方——它的 ticket——所以地图从不复述它，只给 gist 并链接。

**地图、其子 tickets、blocking 和 frontier 查询实际存放在哪是 tracker 特定的。** Issue tracker 本应已提供给你——若没有，运行 `/setup-matt-pocock-skills`。查阅 tracker 文档的 "Wayfinding operations" 一节，了解*本*仓库如何表达它们。若尚未提供 tracker，默认用本地 markdown tracker。

### 地图正文

整张地图的低分辨率视图，每会话加载一次。开放的 tickets **不**列在这里——它们是开放的 child issues，靠查询找到。

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

<!-- 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 -->
```

### Tickets

每张 ticket 是地图的一个 **child issue**；tracker 的 issue id 是其身份。其正文是问题，体量适合一次 100K token 的 agent 会话：

```markdown
## Question

<the decision or investigation this ticket resolves>
```

每张 ticket 带一个 `wayfinder:<type>` 标签——`research`、`prototype`、`grilling`、`task` 之一（见 [Ticket Types](#ticket-types)）。

会话通过把 ticket **认领**给驱动地图的开发者来 claim——**首先**，在任何工作之前，这样并发会话会跳过它。该 assignee *就是*认领：开放且未指派的 ticket 即未认领。

Blocking 使用 tracker 的**原生**依赖关系——这很关键，因为它在 tracker 自己的 UI 里把 frontier *可视化*出来，这样人不用打开地图就能看到什么可领取。只有缺少原生 blocking 的 tracker 才回退到正文约定。当阻塞它的每张 ticket 都已关闭时，ticket 即**解除阻塞**；**frontier** 是开放、未阻塞、未认领的 children——已知的边缘。

答案不是正文的一部分——它在解决时记录（见 [走完地图](#走完地图)）。解决 ticket 期间创建的资产从 issue 链接，而不是粘贴进去。

## Ticket Types

每张 ticket 要么是 **HITL**——人在回路中，与能为自己说话的人一起做——要么是 **AFK**，由 agent 独自驱动。HITL ticket 只通过那场实时交流解决；agent 从不代替人的那一侧（自己回答自己问题的 grilling agent 就破坏了这一点）。

- **Research**（AFK）：阅读文档、第三方 APIs，或知识库等本地资源，挖出某项决策所等待的事实。由 `/research` **subagent** 解决。当需要当前工作目录之外的知识时使用。
- **Prototype**（HITL）：通过做一个便宜、粗糙、具体的产物来提高讨论保真度，供人反应——大纲、粗稿、桩，或经 /prototype skill 的 UI/逻辑代码。把原型作为资产链接。当关键问题是 "how should it look" 或 "how should it behave" 时使用。
- **Grilling**（HITL）：对话。默认情形。始终调用 /grilling 和 /domain-modeling skills。
- **Task**（HITL 或 AFK）：必须发生才能做出*决策*的手工工作——没什么要决定、原型化或调研，但讨论被卡住直到做完。注册某服务以便评判其 API、开通访问、移动数据以便看到其形态。这是唯一*做事*而不是做决策的类型——它靠解锁一项决策赢得席位，而不是交付目的地。Agent 能独自驱动就独自驱动（AFK）；否则交给人一份精确清单（HITL）。工作完成即解决；答案记录做了什么以及后续 tickets 依赖的任何结果事实（凭据位置、新 URLs、行数）。

## 战争迷雾

地图是*故意*不完整的：看不见的就不要画。在活着的 tickets 之外是**战争迷雾**——你能感到即将来临但还钉不下来的决策和调查的朦胧视图，因为它们挂在仍开放的问题上。解决一张 ticket 会清掉它前方的雾，把现在可以规格化的东西毕业成新 tickets——一次一张，直到通往目的地的路清晰且没有 tickets 剩下。

地图的 **Not yet specified** 一节就是写下那朦胧视图的地方：疑似的问题、稍后要回访的区域。它是朝向目的地的未发现 frontier——这里的一切都在范围内，只是还不够锋利，无法做成 ticket。视图允许写多松就写多松、允许多满就写多满；它也是协作者阅读努力走向何处的路标。

**雾还是 ticket？** 检验是你现在能否精确陈述问题——*不是*你现在能否回答它。

- **做成 ticket，当**问题已经锋利——即便它被阻塞、你还不能动手。
- **放进 Not yet specified，当**你还不能那么锋利地措辞。不要预先把雾切成 ticket 大小的块：它比一张 ticket 更粗，一旦 frontier 到达，一块雾可能毕业成若干 tickets，或一张都没有。

**Not yet specified** 排除已经决定的（Decisions so far）、已经是活 ticket 的，以及超出范围的（下一节）。

## 超出范围

雾只朝向目的地聚集。目的地固定了范围，所以超出它的工作是**超出范围**——它不是雾，也不属于 **Not yet specified**。它在地图上有自己的 **Out of scope** 一节：你有意识地划出*本次*努力之外的工作。是范围而不是锋利度让它落在这里。

超出范围的工作永不毕业——frontier 停在目的地——所以只有目的地被重画时它才回来，而且是作为一次新努力，不是恢复。

把某物划出范围是划范围的动作，不是路线上的一步。当一张已存在的 ticket 结果落在目的地之外——绘图时误划进来，或被某次解决暴露——**关闭它**（关闭的 ticket 明确离开 frontier），并在 **Out of scope** 一节留一行：gist 加上为何超出范围，链到关闭的 ticket。它留在 **Decisions so far** 之外，后者记录实际走过的路线——范围边界不是其上的一步。

## 调用

两种模式。无论哪种，**每会话绝不要解决超过一张 ticket**——research tickets 除外。

### 绘制地图

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

1. **命名目的地。** 跑一轮 `/grilling` 和 `/domain-modeling` 会话，钉下这张地图要找到通往何处的路——spec、决策或变更。目的地固定范围，所以先定它。
2. **绘制 frontier。** 再 grill，这次**广度优先**：扇开整个空间，而不是在任一线索上深挖，挖出开放决策和现在可走的第一步。**若这没有挖出雾**——通往目的地的路已经清晰，整段旅程小到一次会话就够——你不需要地图。停下来问用户想怎么继续。
3. **创建地图**（标签 `wayfinder:map`）：填好 Destination 和 Notes，Decisions-so-far 为空，把雾草进 **Not yet specified**。
4. **创建你现在能规格化的 tickets** 作为地图的 child issues——然后在**第二遍**接上阻塞边（issues 需要 ids 才能互相引用）。接线把它们分成 frontier 和被阻塞的；你还不能规格化的一切留在雾里——**Not yet specified** 一节。
5. **发射 research subagents。** 对你刚创建的每张 `research` ticket，拉起一个 `/research` subagent 并行解决，把发现捕获到一次性的 `research/<name>` 分支，并从 ticket 给出上下文指针。
6. 停下——绘图是一次会话的工作；它不手解任何东西。

### 走完地图

用户带着一张地图（URL 或编号）调用。Ticket 是**可选的**——没有的话，由你挑下一个决策，不是用户。

1. 加载**地图**——低分辨率视图，不是每张 ticket 的正文。
2. 选择 ticket。若用户点了名，就用它。否则按顺序取第一张 frontier ticket。**认领它**：在任何工作之前指派给自己。
3. 解决它——**按需放大**：按需拉取任何相关或已关闭 ticket 的完整正文；调用 `## Notes` 块点名的 skills。若有疑问，用 `/grilling` 和 `/domain-modeling`。
4. 记录解决：把答案作为 **resolution comment** 发出，**关闭** issue，并把**上下文指针**追加到地图的 Decisions-so-far。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn