to-spec

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 14 处。

Entry SHA-256: 43ad9cf318e5e7d3d1fa360253a37021796dc87a0c2e595ad262661a10f85088

2. Why This Skill Is Clever

一句话核心机制

把已经完成的对话决策与最新代码库事实压缩成一份可跨会话传递的规格，并在落笔前只保留一个窄而关键的人类确认门：测试 seam。

触发与调用边界

直接来源： frontmatter 的 disable-model-invocation: true 表示它必须由用户显式调用。开头的 “Do NOT interview the user” 又把它放在探索之后：它不是发现需求的工具，而是把已讨论内容定稿为规格。

直接来源： issue tracker 和 triage label vocabulary 是前置条件；缺失时必须让用户先运行 /setup-matt-pocock-skills。技能会发布外部 issue，因此它假设宿主已经提供项目的 tracker 接口和标签语义。

支持性上下文： 仓库文档把 /to-spec 放在多会话构建分支：若工作能在一个 context window 内完成，就直接 /implement；只有需要跨会话保存决定时，规格才值得增加这一步。

信息架构 / 执行顺序

1. 确认前置配置： tracker 与 triage label vocabulary 必须可用。
2. 补齐代码库事实： 必要时探索仓库，读取当前结构，而不是只相信对话记忆。
3. 继承项目语言和约束： 全文使用 domain glossary vocabulary，并遵守相关 ADR。
4. 先设计测试 seam： 优先现有 seam，尽量选择更高层边界，并把总数压到最少。
5. 执行唯一确认门： 只向用户确认 seam 是否符合预期，不重启完整访谈。
6. 按固定模板综合决定： 从用户问题、解决方案、用户故事，逐步进入实现与测试决策，再明确范围外事项。
7. 发布并标记： 将规格写入 issue tracker，直接应用 ready-for-agent，不再进行额外 triage。

最巧妙的设计点

1. 用负面命令把“综合”与“探索”切开

“Do NOT interview the user; just synthesize what you already know.”

直接来源： 技能没有模糊地说“生成规格”，而是先禁止新一轮访谈。这样能防止执行者在会话已经做完决定后再次打开问题空间，也防止规格悄悄混入用户从未确认的新要求。

解释： 好的阶段技能不仅定义要做什么，还定义不得退回哪个上游阶段。这里的负面边界把规格变成 decision record，而不是第二次 discovery。

2. 让代码库事实校正会话记忆

“Explore the repo to understand the current state of the codebase”

直接来源： 对话上下文不是唯一输入；如果尚未探索，必须读取代码库当前状态，并沿用领域词汇、尊重相关 ADR。规格因此同时绑定用户意图与工程现实。

解释： 这避免两类漂移：会话里的模块印象已经过时，以及规格发明了项目没有使用的业务名词。它把“写作一致性”提升为可执行的仓库检查。

3. 只保留一个窄的人类确认门

“Check with the user that these seams match their expectations.”

直接来源： 技能一方面禁止访谈，另一方面要求确认测试 seam。两者并不冲突：它拒绝重新发现需求，但承认测试观察边界是一项成本高、难逆转的实现决策，必须由人确认。

解释： 这是精细的自治边界。执行者可以自主收集事实、起草和发布，但不能替用户决定“从哪里证明功能正确”。

4. 用 seam 数量作为架构压力测试

“The fewer seams across the codebase, the better - the ideal number is one.”

直接来源： 现有 seam 优先于新 seam，新 seam 应尽可能位于高层，而且理想数量是一个。这里不只是测试建议，它也在检测代码库是否拥有稳定、可观察的公共边界。

解释： seam 越多，规格越容易泄漏内部结构，后续测试也越容易随重构破裂。把 seam 设计放在规格前，可以在实现开始前暴露接口碎片化问题。

5. 用双层叙事隔离用户价值与工程决定

“from the user's perspective”

直接来源： Problem Statement 与 Solution 都必须从用户视角写；模块、接口、schema、API contract 和具体交互则被隔离在 Implementation Decisions。Testing Decisions 又独立记录外部行为、测试模块与 prior art。

解释： 这个模板不把所有内容压成一条需求列表，而是保留三种不同证据：用户为什么需要、工程上决定了什么、以后如何证明它正确。下游 agent 可以快速定位自己需要的层。

6. 允许精确代码例外，但防止原型吞噬规格

“Trim to the decision-rich parts, not a working demo”

直接来源： 默认禁止具体文件路径和代码片段，因为它们容易过时；只有当原型片段比文字更精确地编码状态机、reducer、schema 或类型结构时，才允许内嵌，并且必须裁到只剩决策信息。

解释： 这是 fail-closed 的例外设计：先给出简单禁令，再列举何时可破例、可引用什么、必须删掉什么。它兼顾规格的耐久性与复杂决策的精度。

防失败机制与显式不变量

直接来源：

• 缺少 tracker 或 triage label vocabulary 时停止，并引导运行 setup skill；
• 不得重新访谈用户，只能综合已经知道的内容；
• 必要时先探索当前代码库，且必须使用领域词汇并尊重相关 ADR；
• 新 seam 只有在必要时才提出，并应尽可能位于最高层；
• seam 必须先与用户确认，再写规格；
• 规格默认不得包含具体文件路径或代码片段；
• 原型例外必须注明来源，且只能保留 decision-rich parts；
• 测试决策只能针对外部行为，并要指出项目内 prior art；
• 发布后直接应用 ready-for-agent，不得再走一轮重复 triage。

取舍、可移植风险与宿主假设

解释： 强制 LONG、极其详尽的用户故事有利于覆盖面，却可能让架构重构被硬塞进并不自然的“用户想要”句式。固定模板也可能诱使模型为了填满章节而补造决定，因此“只综合已知内容”必须高于模板完整感。技能假设宿主能探索代码库、找到领域 glossary 与 ADR、调用 issue tracker 并正确应用 triage label；迁移到没有这些能力的 harness 时，需要显式提供替代接口。ready-for-agent 还可能被轮询该标签的自动 agent 误解为立即实现整份大规格，而不是等待后续拆票。

支持性上下文： 官方 companion docs 明确承认规格会在实现学习发生后变陈旧，也不会自动搜索 tracker 中的重复工作。它更适合作为一次性的跨会话快照，而不是长期持续同步的真相源。

可迁移原则

1. 为每个阶段写出“不得回退”的边界。 综合阶段禁止重新探索，避免工作流循环。
2. 同时绑定人类语境与现场事实。 对话给出意图，代码库与 ADR 校正可行性和命名。
3. 把人类确认留给高成本边界。 不必逐段审批，但测试 seam 这类难逆转决定必须确认。
4. 先写默认禁令，再设计窄例外。 代码片段默认禁止，只有更精确表达决定时才可裁剪引用。
5. 让交接工件分层承载不同问题。 用户价值、实现决定、测试证据和范围边界应可独立定位。

今日实践题

如果一段对话已经决定要新增“批量暂停订阅”功能，你会从代码库核实哪三类事实、向用户只确认哪个测试 seam，并把哪些尚未讨论的内容明确放进 Out of Scope？

Evidence note

本文关于触发方式、禁止访谈、仓库探索、领域词汇、ADR、seam 选择与确认、规格模板、原型例外、tracker 发布和标签的结论来自所选 SKILL.md。关于多会话触发、规格快照、标签自动化风险和重复工作缺口来自仓库的 docs/engineering/to-spec.md 与路由技能，仅作为支持性上下文。关于阶段边界、自治范围、接口碎片化和可移植性的判断属于设计解释。