to-spec - 把对话直接变成需求规格并发布到 issue tracker

技能概述

to-spec 是 superpowers 技能集中的需求规格生成技能，它不向你提问，而是把当前对话内容和代码库理解直接综合成结构化 spec，并自动发布到项目 issue tracker、打上 ready-for-agent 标签。

适用场景

1. 头脑风暴结束，需要落地成正式文档 你刚和 AI 讨论完一个新功能的做法，思路都在对话里，但还没有一份能给别人看、能照着做的文档。to-spec 直接把这段讨论综合成 spec，不需要你从头复述一遍。

2. 需求讨论完毕，要同步进团队的 issue 系统 spec 写好后自动发布到项目 issue tracker 并打上 ready-for-agent 标签，不需要手动复制粘贴到 Jira、Linear 或 GitHub Issues，也不用手动贴标签。

3. 动手改代码之前，先固定技术方案 to-spec 会先探索仓库、理解现有代码状态，再在 spec 中写清实现决策、测试决策和范围外事项。适合重构前、接新需求前把方案钉死，也适合需要遵守已有 ADR 和领域术语表的项目。

核心功能

1. 无访谈式综合（No Interview Synthesis） 这是 to-spec 最鲜明的特点：它明确不做需求访谈，只综合"你们已经聊过的内容"。适合那些思路已经在对话里成型、只是缺一份正式文档的时刻，省掉一轮问答。

2. 测试 seam 规划与确认 在写 spec 之前，to-spec 会先勾勒出要测试这个功能的接缝（seam）：优先复用已有接缝，优先选最高的接缝，整个代码库的接缝越少越好——理想情况只有一个。新的接缝会尽可能提在最高处，并且会先和你确认这些接缝是否符合预期，再动笔写。

3. 结构化 spec 模板 + 自动发布 按固定模板输出 spec，包含：问题陈述、解决方案、一长串编号用户故事、实现决策、测试决策、范围外说明、补充说明。其中实现决策部分刻意不写具体文件路径和代码片段，避免文档很快过时；唯一例外是原型中编码了比文字更精确的决策时（状态机、reducer、schema、类型形状），会裁剪后内联并注明来自原型。写完后发布到 issue tracker 并直接打上 ready-for-agent 标签，无需额外 triage。

常见问题

to-spec 是什么？和 brainstorming 有什么区别？

brainstorming 是探索阶段——它通过提问帮你想清楚要做什么。to-spec 是收口阶段——它不提问，直接把已经聊清楚的内容综合成一份可发布的规格文档。典型顺序是先 brainstorming 把方案聊透，再用 to-spec 把结论沉淀成 spec 发到 issue tracker。

使用 to-spec 之前需要准备什么？

需要项目里已经配置好 issue tracker 和一套 triage 标签词表，这两项应该已经提供给你。如果没有，to-spec 会提示你先运行 /setup-matt-pocock-skills 完成配置。另外它需要能读到代码库——它会先探索仓库来理解当前状态。

to-spec 生成的 spec 包含哪些部分？

七个部分：问题陈述（从用户视角描述问题）、解决方案（从用户视角描述解法）、用户故事（超长编号列表，覆盖功能各个方面）、实现决策（要建/改的模块、接口、schema 变更、API 契约等）、测试决策（好测试的标准、要测哪些模块、可参考的同类测试）、范围外说明、补充说明。

什么是测试 seam，为什么 spec 里要专门写？

测试 seam 指的是你在哪个接缝上测试这个功能。to-spec 的原则是：已有接缝优先于新接缝，接缝位置越高越好，接缝总数越少越好。spec 里会写明这些决策，并且写之前会先跟你确认接缝选得对不对——因为接缝一旦定错，后面所有测试都会建立在错误的位置上。

to-spec 可以自动触发吗？

不可以。这个技能设置了 disable-model-invocation: true，模型不会自行调用它，需要你手动通过 /to-spec 主动触发。这样设计是为了避免 AI 在你还没聊清楚的时候就急着生成文档。