/to-spec 技能

它的作用

to-spec 把你刚完成的对话变成 spec，并把结果作为单个 issue 发布到你的 issue 追踪器。

它不审问你。等你用到它时，决策已经做完，所以它综合已知信息——从线索、从代码库、从你的 CONTEXT.md 和 ADR——而不是重新开一轮问题。规格说明是已做出决策的记录，不是做出新决策的地方。

何时使用

你通过输入 /to-spec ——这个 agent 不会自动调用它。

当构建对一个智能体来说太大时使用它 会话 并且必须在跨越多个会话的拆分中存活。这就是全部触发条件：

前置条件

to-spec 把规格说明作为 issue 发布，所以 setup-matt-pocock-skills 必须首先为这个仓库配置追踪器和分流标签词汇。两种都可以：GitHub 这样的真实追踪器，或 .scratch/，开箱即可支持。

规格说明是决策记录

规格说明存在，因为上下文窗口会结束。你在 追问审视 ——解决方案的形状、你争论过的选择、你刻意拒绝的东西——都在一段即将被清空的对话里。规格说明正是从那里幸存下来的。

所以它不验证任何东西，也不决定任何东西。它用你项目自己的词汇捕获已被决定的内容，让全新会话无需你重新解释就能接手工作。规格说明断言了任何你从未真正说过的东西，都是缺陷。

先接缝，后散文

在写下一个字之前， to-spec 勾勒 seams 功能将被测试的位置，并与你核对。它偏好已有接缝而非新接缝，并取它能取到的最高的接缝——一个改动跨接缝的理想数量是一。

那些已约定的接缝随后随行。 tdd 只在预先约定的接缝处工作，而且 code-review 对照规格说明审查 diff，所以没人同意的接缝会作为审查发现出现。绑定是间接的——它贯穿这份文档——这正是为什么接缝对话值得在这里认真对待，而不是推迟到实现阶段。

常见问题

原来的 /to-prd 去哪了？ 它就是本技能，在 v1.1 中改名。「Spec」现在是唯一的贯穿性术语，旧的 to-prd slug 已死——用新名字重新安装。取代旧词汇的一对是 spec and tickets：规格说明是目的地以及修正它的决策， tickets 是到达那里的执行步骤。如果你转向，删除未完成的任务，保留规格说明。

为什么规格说明得到 ready-for-agent 标签？我不想让智能体基于它实现。 标签意味着「无需进一步分流」——文档完整到智能体可以据此工作。它是输入指定，不是工作单。但如果你运行 AFK 轮询 ready-for-agent，这个区别对它们不可见，它们会乐此不疲地试图一次跑完整个规格说明，而不是逐个拾取任务切片。这是该技能被反馈最多的粗糙之处。在它改变之前，请在 AFK 智能体的提示词中，或者在 /to-tickets 已经运行过了。

为什么不从审问直接到 /to-tickets 跳过规格说明？ 通常应该——规格说明只在多会话工作中才挣得它的一席之地。它的回报在于任务是可丢弃的而规格说明不是：每个任务都按单个全新 上下文窗口 然后被删除或关闭，而规格说明作为它们背后推理的唯一存身之处留下来。对单会话改动而言，这什么也买不来，你还多付出了一个综合步骤，在那里 model 会漂移。去 追问审视 → /implement.

我刚完成一张 wayfinder 地图。我该喂给它什么？ 主要的地图 issue—— /to-spec #<map_issue>，而不是个别的决策任务。 wayfinder 产出的是散布在地图上的决策，而不是可交付物； to-spec 是把它们折叠成一份可构建文档的步骤。把地图直接循环进 /implement 扔掉那个折叠。

规格说明是给我审查的，还是只给智能体的？ 主要是给智能体的，读起来也确实如此——完整、密集、大量引用。值得你亲自看的是接缝和范围外部分，因为这两处是错误决策最容易抓住、事后发现代价最高的地方。从头到尾读完全文是人们真实存在的抱怨，而且没有摘要模式：诚实的答案是，如果规格说明让你意外，那是审问太浅，而不是规格太长。

任务开始后，规格说明是保持冻结，还是让智能体重写它？ 没有什么让它保持同步，所以实际上它是你那一刻所知内容的快照，而且实现第一次教给你新东西时它就过时了。工作发布后就把它当作一次性的。注定比它长寿的产物是你的 CONTEXT.md 和你的 ADR——如果实现过程中学到的东西值得长久保存，它属于那里，而不是被编辑过的规格说明。

我的工作是重构或模块边界，不是功能。模板合适吗？ 不太行，这是已知限制。模板强烈依赖用户故事，这对架构工作来说形态不对——你最终会围绕真正关于接口和不变量的决策，写出没人要的故事。请改用实现决策和测试决策部分，让持久的架构决策通过 grill-with-docs 而不是试图让规格说明承载它们。

它会检查追踪器中相关工作，或引用它尊重的 ADR 吗？ 两者都是不。它读取并尊重其触及领域的 ADR，但不链接它们，起草前也不搜索追踪器中重叠的 issue——所以规格说明可能悄悄重复某人已提交的工作。如果该领域很忙，请自己先搜索追踪器。

/to-tickets 读不了我的规格说明——它一直在截断。 非常大的规格说明可能超出追踪器 issue 能干净回读的范围，而且没有本地副本可兜底。修复是上下文卫生：不要 clear or compact between /to-spec and /to-tickets。在同一个窗口中运行它们，规格说明就完全不需要再被重新获取。

做到以下就算成功

• 它开始写作，而不是问你新一轮问题。
• 它在写之前把接缝摆给你，并且尽量少提。
• 它以你项目的名词返回，而不是通用的产品管理套话。
• 其中的每个决策都是你记得自己做出的。没有任何东西是为了填满章节而虚构的。
• 范围外部分有真实的东西——你拒绝的东西通常是页面上最有用的几行。

在流程中的位置

to-spec 是主构建链上的一步，而且只在它的多会话分支上：

grill-with-docs → to-spec → to-tickets → implement → code-review

它上游的邻居是 grill-with-docs，它负责做出该技能只负责记录的决策，而 wayfinder，其完成的地图正好在这里汇入链条。下游， to-tickets 把规格说明切成 implement 构建。当你不确定哪个技能或流程合适时， ask-matt 为你指路。