wayfinder

Wayfinder — 寻路，而不是冲向终点

一个宏大的想法刚刚出现——对一个 Agent 会话来说太大了，而且笼罩在迷雾中：从这里到终点的道路还没有显现。寻路就是找出这条路，而不是径直冲向终点。此技能会在 issue 账本上把道路绘制成一张地图，然后逐个处理其中的决策 ticket——每个 ticket 都是一个答案为某项决策的问题，而不是一块构建工作——直到通往终点的道路清晰，不再有待决事项。

这是 /propose 之前的一步：propose 假定工作的大致形态已经明确；wayfinder 则用于尚不明确的时候。

WHAT

目的和上下文

• 目的： 为一块过大且模糊的工作找到通往终点的道路——在 issue 账本上绘制决策 ticket 地图，然后逐个解决 ticket，直到道路清晰，不再有待决事项。
• 触发条件（何时使用）： 当一个宏大想法的形态尚不明确时，手动调用，且要在 /propose 之前。仅手动调用（disable-model-invocation: true）。
• 非目标： 不生成交付物／构建结果（那是 /propose 之后的事）；不替 HITL ticket 中的人类一方作答；不把迷雾预先切成 ticket；不解决终点之后的工作（超出范围）。

心智模型

宽泛的想法 → Destination → 地图（issue wayfinder:map，索引）→ 决策 ticket（子 issue，阻塞边）→ 前沿 → 解决一个 ticket → 已做决策 + 清除迷雾 → … → 道路清晰 → 移交 /propose。

规划，而非执行

Wayfinder 默认用于规划：每个 ticket 解决一项决策；当道路清晰时，地图就完成了——在有人动手之前，不再有待决事项。让你想要动手执行的冲动，通常表明你已经来到地图边缘，该移交给 /propose 了。生成决策，而非交付物。

用名称称呼，不用 id

每张地图和每个 ticket 都是一个 issue，因此都有一个名称——也就是它的标题。在所有面向读者的内容中（叙述、已做决策），都用名称来称呼，绝不要只用 id。#42, #43, #44 这样的墙读不懂；名称一眼就能看懂。id 和链接并没有消失——名称会包住链接——但它们应该放在名称里，而不是取代名称。

四种 ticket 类型

每个 ticket 都是 HITL（由真人作答）或 AFK（Agent 独自运行）。HITL ticket 只能通过实时交流来解决；Agent 绝不能代替人类一方——一个自己回答自身问题的 grilling Agent 就违反了这一原则。

• research（AFK）——阅读文档／API／知识库，找出某项待决决策所需的事实。通过一个 subagent /research（或 /agent-reach）来解决。需要当前目录之外的知识时使用。
• prototype（HITL）——用具体的粗略成果来提升讨论的精细度，以便收集反馈：提纲、草稿、stub 或 UI／逻辑。主要问题是“看起来怎样”或“行为如何”时使用。
• grilling（HITL）——一次问一个问题的对话。默认类型。
• task（HITL 或 AFK）——必须由人完成的工作，只有完成后才能作出某项决策：注册一项服务以评估其 API、获取权限、迁移数据以了解其形态。这是唯一一种执行而非决策的类型——它之所以值得占据位置，是因为它能解锁一项决策，而不是因为它交付了成果。

战争迷雾

地图有意保持不完整：不要绘制尚未看见的内容。活跃 ticket 之外的部分是迷雾——对已知将会出现、但尚无法固定下来的决策的模糊认知，因为它们取决于尚未解决的问题。解决一个 ticket 会清除它前方的迷雾，让此时已能明确的问题都成为新的 ticket——一次一个，直到通往终点的道路清晰。

迷雾还是 ticket？ 判断标准是现在能否把问题准确地表述出来——而不是现在能否回答。

• 问题已经明确时，建立 ticket——即使它被阻塞、暂时无法处理。
• 尚无法准确表述时，标记为 Not yet specified。不要把迷雾预先切成 ticket 大小的碎片：它比 ticket 更粗略；当前沿抵达时，一片迷雾可能具体化为多个 ticket，也可能一个都没有。

不在范围内

迷雾只会朝着目标方向聚拢。目标固定了范围，因此超出目标的内容属于不在范围内——它不是迷雾，也不属于尚未指定。它有自己的栏目：你有意识地将其排除在本次工作之外的内容。不在范围内的内容永远不会从迷雾中毕业。如果某个已存在的 ticket 结果发现位于目标之后 → 关闭它，并在“不在范围内”中留下一行，不要在途中解决它。

输入和输出约定

	字段	必填？	含义
输入	松散的想法	是（Chart 模式）	需要寻找路径的事物
输入	地图（issue wayfinder:map）	是（Work 模式）	已构建的地图
输入	具体 ticket	否（Work 模式）	未指定 → 选取第一个 frontier ticket
输出	地图 issue + 子 issue + 阻塞边	Chart	Destination、勾勒迷雾的 Not-yet-specified、空的 Decisions-so-far
输出	一个已认领 → 已解决 → 已关闭的 ticket + Decisions-so-far 中的指针	Work	包括新显现的 ticket / 迷雾毕业 / 更新后的不在范围内

规则和能力

• RULE-01（MUST）：仅手动调用（disable-model-invocation: true）——wayfinder 是用户有意发起的操作，不是模型自行启动的东西。参见 [[skill-craft]]。
• RULE-02（MUST）：规划，不执行——产出决策，不产出交付物。想要开始执行 = 到达地图边缘 = 移交给 /propose。
• RULE-03（MUST）：每个会话处理一个 ticket（研究除外），并且先认领再处理（使用 frontier.py + ledger 的 claim 栏）。
• RULE-04（MUST）：Ledger 是事实来源；远程 tracker 是镜像。关于本仓库中的措辞，参见 [[issue-tracker]]。
• 能力：在 ledger 上读取/写入 issue（创建、连接阻塞边、认领、关闭）；查询 frontier；与用户就 HITL ticket 进行实时对话；并行启动 research 子代理。

失败边界

• 绘制 frontier 后没有显现任何迷雾 → 路径已清晰，无需地图：停止，询问用户想如何继续。
• HITL ticket 没有人回答 → 阻塞；agent 不会代替用户回答。
• ticket 已被其他会话认领 → 不要解决；选择其他 frontier ticket。
• 解决方案表明内容位于目标之后 → 关闭 ticket，并记录在“不在范围内”（该 ticket 标记为 cancelled）。
• 一旦想要开始执行 → 到达地图边缘 → 移交给 /propose。

HOW

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	想法	（Chart）通过 /grilling + /domain-modeling 为目标命名	一句话的 Destination	—
W02	judgment	Destination	（Chart）按广度绘制 frontier	开放决策 + 第一步	没有迷雾 → 停止，询问用户
W03	effect	W01–W02	（Chart）创建地图 + 可固定的 ticket，并连接第二轮阻塞边	map issue + 子 issue	—
W04	effect	research ticket	（Chart）并行启动 research 子代理，然后停止	附带指针的发现	—
W05	deterministic	地图	（Work）加载地图，选择 ticket（用户指定或 frontier.py --map <id>），先认领	已认领的 ticket	已被认领 → 选择其他 ticket
W06	judgment	ticket	（Work）解决——必要时缩小范围；HITL 时询问真人	解决方案	陷入困境 → /grilling + /domain-modeling
W07	effect	解决方案	（Work）记录 resolution，关闭 issue（status: done），追加到 Decisions-so-far；创建新 ticket / 让迷雾毕业 / 排除为不在范围内	更新后的地图	—

各步骤详情（W01–W07 的事实来源）：

两种模式。两者都绝不在一个会话中解决超过一个 ticket——研究除外。

绘制地图（dựng bản đồ）

用户带着一个模糊的想法来找你。

1. 命名目的地。 运行 /grilling + /domain-modeling（如果有），确定这次要探索什么。目的地会固定范围，因此要先确定。→ 完成条件： 一句话的 Destination，能为之后的每个会话指明方向。
2. 绘制前沿。 再次 grilling，横向展开：遍历整个空间，而不是沿一条路径深入，找出尚待决定的事项和可以立即采取的第一步。如果没有发现任何迷雾 → 路径已清晰，不需要地图；停止并询问用户接下来想怎么做。
3. 创建地图（标签 wayfinder:map）：填写 Destination 和 Notes，Decision-so-far 留空，将迷雾草拟到 Not-yet-specified。
4. 创建可固定的 ticket作为子 issue——然后在第二轮添加阻塞边（issue 需要先有 id 才能互相引用）。→ 完成条件： 所有可固定的 ticket 均已创建，尚不能固定的部分留在迷雾中。
5. 启动 subagent research。 每个 research ticket → 一个 subagent 并行解决，记录发现，并从 ticket 附上上下文指针。
6. 停止——绘制地图是一个会话的工作；它不会自行解决任何 ticket。

按地图推进（làm qua bản đồ）

用户带着一张地图来找你。Ticket 是可选的——如果没有 ticket，就由你选择下一个决定事项，而不是让用户来选。

1. 加载地图（低分辨率视图，而非所有 ticket 正文）。
2. 选择 ticket。用户指定了就用指定的。否则取第一个前沿 ticket（frontier.py --map <id>）。认领它——在进行任何工作之前填写 claim 字段。
3. 解决——按需深入：根据需要获取相关 ticket 的完整正文；调用 Notes 中点名的技能。如果卡住了，运行 /grilling + /domain-modeling。
4. 记录解决方案：将解决方案发布为 resolution，关闭 issue（status: done），并向地图的 Decisions-so-far 追加一个指针。
5. 添加新发现的 ticket（先创建再连接）；将刚被解决方案固定的迷雾内容毕业，并从 Not-yet-specified 中移除。如果解决方案发现某个 ticket 位于目的地之后 → 标记为超出范围。如果解决方案否定了地图中的其他部分 → 更新或删除该 ticket。

分支

ID	Kind	Guard	行为	跳过 / 失败	Rejoin
B01	user_optional	用户带着现有地图来找你	切换为按地图推进模式（W05–W07），而非绘制地图模式（W01–W04）	—	在一个 ticket 后结束会话
B02	conditional_required	research 类型的 ticket	使用 subagent /research（或 /agent-reach）解决，可并行处理多个 ticket	—	W07
B03	conditional_required	HITL ticket（prototype/grilling/task-HITL）	只能通过与人的实时交流来解决	没有人 → blocked	W07
B04	recovery	解决方案否定了地图中的其他部分	更新或删除该 ticket	—	W07

验证与停止条件

绘制地图在 W04 后停止（不会自行解决任何 ticket）。按地图推进时，恰好在一个 ticket 后停止（research 除外）。当通往目的地的路径清晰且没有待决定事项时，地图即告完成 → 移交给 /propose。下一个 ticket 由 frontier.py + claim 字段决定，不要猜测。

示例

• 正向：“/wayfinder 将 overstack 转换为 multi-model dispatch” → 通过 grilling 得出一行 Destination，前沿显露出 3 个 ticket（1 个关于 provider API 的 research，2 个 grilling）→ 创建 wayfinder:map 地图和 3 个子 issue，第二轮添加阻塞边，启动 1 个 subagent research → 停止。
• 边界/失败：“/wayfinder ”，但前沿 ticket 是 grilling（HITL），而用户不在场 → blocked，Agent 不会自行回答自己的问题；本次会话不解决第二个 ticket。

参考 — 地图

地图是 ledger 上的一个 issue（标签 wayfinder:map）。它的 ticket 是子 issue。地图是一个索引，而不是仓库：它列出已做出的决定，并指向保存详细信息的 ticket——每项决定只保存在一个位置（对应的 ticket 中），地图不会复述，只会提供概要和链接。地图、子 ticket、阻塞边以及 frontier 查询的存放位置由具体 tracker 决定——请阅读 [[issue-tracker]] § “Wayfinding operations”。

地图正文（每个会话加载一次）：

## Destination
<đi tới cuối bản đồ này trông như thế nào — spec, quyết định, hay thay đổi mà nỗ lực này tìm đường tới. Một hai dòng; mỗi phiên định hướng vào nó trước khi chọn ticket.>

## Decisions so far

- [<tên ticket đã đóng>](link) — <gist một dòng của lời giải>

## Not yet specified


## Out of scope

Ticket 是子 issue，正文是问题，规模适合在一个会话中处理：

## Question
<quyết định hay điều tra mà ticket này giải>

Origin

• Chưng cất từ mattpocock/skills — skills/engineering/wayfinder/SKILL.md (clone scratchpad/mattpocock-skills/, 2026-07-15).
• Absorb qua /propose → 150726-mattpocock-absorb (T8), task T-260715-01. Đứng trên hạ tầng ledger T6/T7.
• Commit: (verify-before-commit điền)