spec-drafting

name	spec-drafting
description	Spec 起草技能。当用户提供原始需求（自然语言描述或 docs/intake/xxx.md 文件），需要将其转化为符合 spec-template 格式的 spec 文档时使用。适用于执行 /spec-draft 命令时触发，或用户直接说"帮我把这个需求写成 spec"时。

Spec 起草

把原始需求（口语化、非结构化）转化为符合 specs/templates/spec-template.md 格式的 spec 文档草稿。

核心原则（必读）

1. AI 是起草助手，不是业务方：业务目标、ROI、验收标准的最终拍板权在人，AI 不能臆造
2. 必须主动问澄清问题：原始需求里的歧义不能默默假设，宁可问 5 个问题也不要硬填
3. 标注信息来源：每个章节内部要分清「原始需求覆盖 / AI 推断 / [TBD] 等人补」
4. 输出 status 一定是 draft：不允许直接 ready，必须经人 review

⚠️ 与 spec-analysis 区别：spec-analysis 是分析已有 spec；本 skill 是从无到有起草 spec。

执行步骤

Step 1: 收集原始需求

• 用户给 docs/intake/xxx.md 路径 → 读取文件
• 用户直接描述 → 先复述理解，确认无误后开始
• 两者都有 → 以文件为主，对话为补充

Step 2: 扫描上下文（调用 codebase-survey light 模式）

调用 skills/codebase-survey/SKILL.md，传入参数 mode: light，输出包含：

• 相关模块清单
• 可复用资产
• 冲突 / 重叠提示
• 推荐参考的代码模式
• 初步影响估计

侦察报告将合并到 spec 草稿的：

• 「实施备注」 章节
• 「关键代码参考」 表格（如果模板有此章节，否则放在「实施备注」末尾）
• 「风险与未决问题」（侦察发现的不确定项）

⚠️ Light 模式不进入实现细节。如果 spec 起草过程中确实需要看到某个函数的实现细节，标记为 [TBD]，留到阶段二的 deep 模式再处理。

Step 2.5: 索引检查 + 多 spec 检测

• 扫描 specs/<VERSION>/ 目录了解现有 spec（必要时也可参考 团队 Wiki 索引：）
• 检查是否有现有 spec 与新需求重叠 / 冲突（codebase-survey 已部分覆盖，此处再确认 spec 层）
• 确认 Story ID（从 docs/intake 头部 / 用户提供 / 默认 0 占位）
• 多 spec 检测：扫描 specs/ 目录看是否已有同 Story ID 的 spec 文件
  • 如有，必须主动询问用户「新建子 spec / 修改已有 / 换 Story ID」三选一
  • 如确认新建子 spec，slug 必须与已有 spec 不重复，并在新 spec 的 Sibling Specs 字段引用兄弟 spec

Step 3: 列出澄清问题（关键步骤，不可跳过）

在生成 spec 草稿之前，先列出 2-5 个最关键的不清楚点等用户回答：

必问类别	问题示例
业务目标边界	"这个功能要解决谁的什么问题？成功的衡量指标是什么？"
用户角色	"调用方是 APP 用户、内部服务，还是第三方？"
验收标准	"怎样算做完了？至少需要哪几条可验证的标准？"
非功能要求	"性能 / 安全 / 兼容性是否有特殊要求？"
范围边界	"这一期不做哪些事？"

Step 4: 起草 spec（按模板章节分类来源）

章节	来源标记	处理原则
标题 + 元信息	🤖 AI 推断	编号取 INDEX 下一个；slug 用 kebab-case
背景	📥 原始需求复述	不要扩写，忠实复述 + 已有 spec 关联
目标	📥 原始需求 / ❓ TBD	不能臆造；原始需求未说清楚就标 [TBD]
非目标	🤖 AI 建议	推断后必须标"建议非目标，待人确认"
用户故事	📥 原始需求	"作为... 我希望... 以便..." 三段式
功能需求	📥 原始需求 + 🤖 AI 拆解	拆为 FR-1, FR-2...；每条独立可验证
非功能需求	📥 原始需求 / ❓ TBD	性能/安全/兼容性，原始需求没说就标 [TBD]，不要默认值
数据结构 / API	📥 原始需求 + 🔍 现有代码	参考已有代码定义，避免重复造轮子
状态流转	📥 原始需求 / ❓ TBD	不能臆造状态机
边界情况	🤖 AI 推断	标注"AI 推断的边界，待 review"；尽量列全
验收标准	📥 + 🤖 + ❓	关键章节，AI 起草建议但必须人逐条确认
测试点	🤖 从验收标准推导	—
风险与未决问题	🤖 + ❓	把所有不确定的列出来标 open
实施备注	🤖 + 🔍	给参考代码路径
修订记录	🤖 占位	初始版本，留空表头

Step 5: 写入文件

• 路径：specs/<VERSION>/<STORYID>-<slug>.md
  • STORYID：纯数字 Story ID（不强制唯一——大需求拆分时多个 spec 可共享）；如无对应 story 用 0 占位
  • <slug>：kebab-case 简短描述（同 Story 下必须唯一，是真正的 spec 区分键）
  • 例：specs/v1.6.0/10088-payment-retry.md
  • 大需求拆分例：specs/v1.6.0/10086-example-gateway.md、specs/v1.6.0/10086-example-controller.md
• frontmatter：
  • Story ID: <数字>（与文件名保持一致；追溯线索，非唯一标识）
  • Sibling Specs: [...]（可选；如本 spec 是子 spec，列出同 Story 下的兄弟 spec 路径）
  • Status: draft（强制，不可改）
  • Author: [作者名 / TBD]
  • Created: <当前日期>
  • Updated: <当前日期>

Step 6: 输出起草报告

### Spec 起草报告：[Story ID] [标题]

**已写入**：specs/<VERSION>/<STORYID>-<slug>.md（status: draft）

**章节完成度**：
- 📥 来自原始需求：[章节列表]
- 🤖 AI 推断（请 review）：[章节列表]
- ❓ 标 [TBD] 待补充：[章节列表 + 缺什么]

**关键澄清问题（请先回答这些）**：
1. [问题 1]
2. [问题 2]
3. [问题 3]

**与现有 spec 的关系**：
- 复用：[已有 spec/代码]
- 冲突：[如有]
- 衔接：[如有]

**建议下一步**：
1. PO/架构师 review draft
2. 回答上述澄清问题
3. 把 status 从 `draft` 改为 `ready`
4. 执行 /spec-plan 进入阶段二

注意事项

❌ 不要做

• 替业务方拍板「目标」「验收标准」「ROI」
• 假设非功能需求（如"默认要求性能 < 100ms"——除非原始需求或项目规则明示）
• 把 Status 直接设为 ready
• 不问澄清问题就硬填章节
• 在草稿里写"已完成 / 已确认"措辞

✅ 鼓励做

• 留 [TBD] 比错填更好
• 列澄清问题比硬猜更好
• 引用已有 spec / 代码作为参考
• 在「风险与未决问题」里把不确定的全暴露出来
• 推断的部分明确标注「AI 推断，请 review」

输出格式参考

参见 specs/v1.6.0/0-example-feature.md 与 specs/v1.6.0/10086-example-user-login.md 的实际章节结构。

关联资产

• 模板：specs/templates/spec-template.md
• 规则：rules/10-spec-workflow.md 阶段零
• 命令：commands/spec-draft.md