[Skills-03] From Conversation to an Executable Map: Specs, Tickets, and Wayfinding

需求对齐以后，真正的风险是信息在从聊天到实现的转换中丢失。这个主题的四个 skill 分别回答：如何固化共识、如何切工作、如何探索超大未知，以及如何把暂时无法回答的决策交给另一个人。

1. to-spec：规格描述稳定决策，不描述易腐代码#

to-spec 不再进行新一轮访谈。它把当前 conversation、领域文档、ADR 和代码现状综合成一个可发布到 issue tracker 的 spec。

标准结构包括：

• Problem Statement：从用户视角描述问题；
• Solution：描述期望体验，而非实现细节；
• User Stories：把 actor、行为和收益连接起来；
• Implementation Decisions：已确认的模块边界、约束和取舍；
• Testing Decisions：在哪些 seam 验证什么行为；
• Out of Scope：明确这次不解决什么。

它刻意避免具体文件路径和大段代码，因为这些信息比行为决策腐化得快。只有原型中一段状态机、schema 或 type shape 能比自然语言更准确表达决定时，才值得保留精简代码。

测试 seam 应尽可能高。一个端到端 seam 能覆盖完整行为时，不要为了“单元测试数量”在内部制造大量 seam。新增 seam 本身就是架构成本。

2. to-tickets：按 tracer bullet 切，而不是按技术层切#

坏的拆票方式：

Ticket A: 建表
Ticket B: 写后端 API
Ticket C: 写前端
Ticket D: 补测试

这种 horizontal slicing 让前几个 ticket 无法独立验证价值。更好的 tracer bullet 是一个端到端行为：

Ticket A: 用户能创建一条最小草稿并再次打开
Ticket B: 用户能发布草稿并看到公开页
Ticket C: 未授权用户不能编辑已发布内容

每张 ticket 只需要稳定字段：用户可感知的交付、acceptance criteria、blocking edges。文件路径和实现片段仍然尽量不写。

2.1 先画依赖，再追求并行#

Ticket 不是一个按顺序执行的长列表，而是 DAG。所有 blocker 已完成的 ticket 构成 frontier，Agent 可以从 frontier 并行领取。

01 最小创建流程 ─┬─> 03 发布流程
                 └─> 04 权限拒绝
02 账户识别 ─────────> 04 权限拒绝

2.2 Wide refactor 是例外#

一次 schema rename 可能瞬间破坏几千个调用点，无法切成持续绿色的用户纵向行为。这时采用 expand-contract：

1. Expand：新旧形式并存；
2. Migrate：按 package 或 blast radius 分批迁移；
3. Contract：所有迁移完成后删除旧形式。

这不是放弃增量交付，而是在机械性横向变更中维护可回滚性和依赖关系。

3. wayfinder：大型未知需要决策地图，不是超长 todo#

当一项工作大到一个 Agent session 无法装下，而且到目标的路线尚不可见时，普通 spec 会过早制造确定性。Wayfinder 创建一个 map issue，记录：

• Destination：地图终点是什么；
• Decisions so far：已关闭 decision ticket 的一句话索引；
• Not yet specified：知道存在、但还无法准确提问的 fog；
• Out of scope：明确在目标之外的工作。

Map 是索引，不复制 ticket 的完整答案。每个开放 ticket 只解决一个 session 能容纳的 decision，产出“决定”，而不是实现 deliverable。

3.1 四种 decision ticket#

3.2 Fog of war 不是 backlog#

判断应该建 ticket 还是留在 fog 的标准，不是“现在能不能回答”，而是“现在能不能准确提出问题”。能准确提问，即使被 blocker 卡住，也应该建 ticket；连问题边界都说不清，就继续留在 Not yet specified。

每解决一个 ticket，新的视野可能让一块 fog 变成一个或多个 ticket，也可能证明它不再重要。地图因此是逐步展开的，而不是启动时假装知道全部未来。

3.3 地图清晰后要回到主流程#

Wayfinder 的终点通常不是直接 implement，而是回到 to-spec，把分散的决策折叠为单一可构建计划，再用 to-tickets 切交付工作。探索图和执行图承担不同职责。

4. to-questionnaire：把未知交给正确的人#

这是一个 in-progress skill。它适合“决策依赖某位同事，但对方无法立即加入会话”的场景。

Agent 不去采访问卷发起人关于主题本身，而是问清楚这次 send：

• 收件人是谁、掌握什么信息；
• 需要对方返回决定、事实还是偏好；
• 哪些问题存在前置依赖；
• 回答将阻塞什么后续工作。

然后生成适合异步填写或会议共同填写的 Markdown。好问卷不是把所有疑问倾倒给别人，而是提供背景、选项、推荐和明确的返回格式，减少来回沟通。

5. 四种工件不要混用#

最常见的错误是把四者都写成 todo list。真正可靠的规划系统会区分“已定决策”“待交付行为”“待探索问题”和“等待外部输入”。

参考#

• to-spec
• to-tickets
• wayfinder
• to-questionnaire（in progress）