spec-driven-brainstorm

你将协助用户把早期构想转化为规范驱动的变更提案。

此技能的命令

如果你记不清此技能使用的确切命令，请在运行任何命令前到此处查找。不要猜测。

propose: node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
verify: node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>

前提条件

.spec-driven/ 目录必须位于项目根目录。继续之前，请先验证：

ls .spec-driven/

如果验证失败，说明项目尚未初始化。请先运行 /spec-driven-init。

步骤

1. 从构想出发，而非产物清单——询问用户希望实现什么、要解决什么问题，以及已知的限制或偏好。不要一开始就要求用户提供变更名称。

2. 尽早阅读项目背景和现有规范——在缩小范围之前，阅读：

   • .spec-driven/config.yaml——将 context 作为项目背景，并将 rules 视为必须遵守的约束
   • .spec-driven/specs/INDEX.md——确认是否已有涵盖所请求行为的规范领域
   • INDEX.md 中引用的、与当前构想相关的所有主规范文件

3. 充分讨论，直到变更方案可供决策——通过讨论明确：

   • 期望结果和用户可见的行为
   • 变更的范围，以及明确排除在范围之外的内容
   • 重要的权衡、约束、风险和保持不变的行为
   • 可能需要修改的现有规范文件，或是否需要新增规范领域
   • 实施前仍需由人工回答的问题

4. 建议变更名称——构想足够明确后，提出一个简短的 kebab-case 变更名称。如果用户已提供有效名称，则保留该名称。否则，建议一个能体现双方已商定变更范围的名称。

5. 提供提案确认点——创建任何文件之前，总结：

   • 建议的变更名称
   • 目标和范围
   • 预计会变更的主要规范领域
   • 已确定的关键决策或权衡
   • 需要写入 questions.md 的未解决问题

   然后请求用户明确确认。如果用户希望修改内容，继续讨论并重新总结，直到用户确认。

6. 确认后搭建变更目录结构——运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
   

   此命令会创建 .spec-driven/changes/<name>/，并放入预置模板。

7. 填写五份提案产物——搭建目录结构后，完成与 /spec-driven-propose 相同的提案工作流：

   • 编写 proposal.md，包含 What、Why、Scope 和 Unchanged Behavior

   • 编写 design.md，包含 Approach、Key Decisions 和 Alternatives Considered

   • 在 changes/<name>/specs/ 中填写增量规范文件，并使路径与主 .spec-driven/specs/ 结构对应

     • 完全镜像主规范路径，例如，.spec-driven/specs/skills/planning.md 对应 .spec-driven/changes/<name>/specs/skills/planning.md

     • 以此规范示例为格式参考：

       ---
       mapping:
         implementation:
           - path/to/implementation.ts
         tests:
           - test/path/to/test.ts
       ---
       
       ## ADDED Requirements
       
       ### Requirement: new-capability
       The system MUST provide <observable behavior>.
       
       #### Scenario: success
       - GIVEN <precondition>
       - WHEN <action>
       - THEN <result>
       
       ## MODIFIED Requirements
       
       ### Requirement: existing-capability
       Previously: The system MUST <old behavior>.
       The system MUST <new behavior>.
       
       ## REMOVED Requirements
       ### Requirement: old-capability
       Reason: 此行为已移除，原因是 <reason>。
       

     • 省略不适用的章节，而不是留下空白占位符

     • 如果变更对可观察到的规范没有影响，请将 changes/<name>/specs/ 留空，而不是创建只有说明文字的差异文件

     • 如果仓库证据不明确，不要臆造 mapping.implementation 或 mapping.tests 路径

   • 在相关文件可从仓库上下文中确定时，在差异规范文件的 frontmatter 中 包含 mapping.implementation 和 mapping.tests

   • 按以下规范结构编写 tasks.md：

     # Tasks: <change-name>
     
     ## Implementation
     - [ ] Describe the first atomic implementation task
     - [ ] Describe the second atomic implementation task
     
     ## Testing
     
     - [ ] Run `npm run lint` — lint or validation task
     - [ ] Run `npm test` — unit test task
     
     ## Verification
     - [ ] Verify implementation matches proposal scope
     

     每项任务都使用 - [ ] 复选框，并且应可独立完成。

     ## Testing 章节必须满足以下验证关键词要求：

     • 至少一项任务必须包含 lint/validation 关键词：lint、validate、 validation、typecheck、type-check 或 build
     • 至少一项任务必须包含单元测试关键词：unit test 或 unit tests
     • 两项任务都必须在反引号中注明明确可运行的命令，或使用已知的 运行器（npm、pnpm、yarn、bun、node、bash、sh、pytest、jest、vitest、go、cargo、 make、uv、poetry）
     • 改述这些关键词（例如用“运行测试”代替“运行单元测试”）会导致 verify 失败

     如果无法根据仓库上下文有把握地确定相关命令，请将此情况记录在 questions.md 中，而不要猜测。

   • 编写 questions.md，将所有未解决的问题记录在 ## Open 下；如果没有不明确之处， 则留空

8. 提交方案前进行验证 — 运行：

   node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
   

   • 立即修复任何安全的产物格式问题，并重新运行 verify
   • 如果只剩未解决的问题，则将其视为方案阶段的预期情况，并 清楚列出这些问题
   • 如果仍存在任何非问题类错误，则停止并报告该错误，而不要将方案作为已就绪方案提交

9. 像 propose 一样交接 — 向用户展示生成的产物，总结 最终提议的范围，并列出 /spec-driven-apply 前必须回答的所有未解决问题。

10. 提供自动交接选项 — 交接后，询问用户是要进入 /spec-driven-auto 端到端执行方案，还是继续使用 /spec-driven-modify 修改方案。未经用户明确选择，不要自动进入 auto。

规则

• 不要实现代码 — 此技能仅用于规划
• 在用户明确确认头脑风暴摘要和变更名称之前，不要生成方案产物
• 在确定范围或编写差异规范前，读取 .spec-driven/config.yaml、INDEX.md 和相关主规范
• 如果用户一开始只提出粗略想法，请建议一个 kebab-case 变更名称
• 在 questions.md 中记录尚未解决的歧义；不要默默猜测
• 如果无法从仓库上下文确定测试命令，请将此情况记录在 questions.md 中，而不要臆造命令
• 确认后，遵循与 /spec-driven-propose 相同的产物编写和验证标准
• 在规范 frontmatter 中记录实现和测试映射，而不要写在需求说明文字中