| name | spec-drafting |
| description | Spec 起草技能。当用户提供原始需求（自然语言描述或 docs/intake/xxx.md 文件），需要将其转化为符合 spec-template 格式的 spec 文档时使用。适用于执行 /spec-draft 命令时触发，或用户直接说"帮我把这个需求写成 spec"时。 |
Spec 起草
把原始需求（口语化、非结构化）转化为符合 specs/templates/spec-template.md 格式的 spec 文档草稿。
核心原则（必读）
- AI 是起草助手，不是业务方：业务目标、ROI、验收标准的最终拍板权在人，AI 不能臆造
- 必须主动问澄清问题：原始需求里的歧义不能默默假设，宁可问 5 个问题也不要硬填
- 标注信息来源：每个章节内部要分清「原始需求覆盖 / AI 推断 / [TBD] 等人补」
- 输出 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
