| name | module-intent-writer |
| description | 将功能模块转化为业务意图文档，面向业务方和测试人员的业务契约。 触发场景：(1) 用户需要为模块编写意图文档；(2) 用户提到"意图文档"、"intent document"； (3) 用户需要做"业务意图澄清"、"需求澄清"、"intent writing"； (4) 用户要为模块做"业务对齐"、"业务设计"；(5) 模块设计流水线被调度执行时。 按四步连续流程执行：意图澄清 → 书写授权 → 生成意图文档 → 冻结授权。 每次调用为指定单一模块输出一份意图文档。
|
Module Intent Writer
将设计文档中的功能模块转化为业务意图文档——面向业务方和测试人员的业务契约，明确"做到什么程度算完成"。
意图文档是模块开发流水线的第一阶段输出，经用户冻结确认后，作为后续技术规格编写的强制输入。
核心原则
- 业务语言优先：意图文档使用业务方可理解的语言，禁止混入技术实现细节。
- 多轮澄清：核心模块必须通过多轮问答彻底澄清业务需求，禁止跳过澄清直接生成。
- 门控机制：书写授权与冻结授权为两个独立门控，必须分别获得用户显式确认。
- 冻结不可变：冻结后的意图文档作为后续 spec-writer 的强制输入，不可擅自修改。如需修改必须通过回退机制重新解冻。
- 禁止偷懒：文档中禁止出现"等等"、"..."、"其他字段"等偷懒表述，每个字段必须有完整业务定义。
- 中文输出：所有输出文本使用中文，代码与专有名词除外。
- 增量意识：感知当前运行模式（full_design 或 design_docs_only_intent_draft），在草稿续写时从已有文档恢复状态。
前置输入
本 Skill 启动时接收以下模块标识参数：
| 参数 | 说明 |
|---|
module_id | 模块编号（如 M02） |
module_name | 模块名称（如"世界观构建引擎"） |
module_type | 模块类型：🔴 核心 或 🟢 一般 |
module_group | 所属分组（如 02-内容生成域，已标准化为目录前缀） |
incremental_mode | 增量模式：full_design 或 design_docs_only_intent_draft |
路径构造
严格遵守 directory-convention.md 规定的目录结构。产物路径为：
docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-意图文档.md
[序号]-[分组] 来自启动时注入的 module_group（已标准化，禁止再次推断）[编号]-[名称] 来自启动时注入的 module_id 和 module_name
输入材料收集（按需）
在执行具体步骤前，从以下来源收集材料。仅读取当前模块相关的内容，不再扫描全部模块：
- 功能模块全拆解表：
docs/功能设计/功能模块全拆解.md，定位当前模块所在行，提取核心功能、颗粒度描述、设计文档溯源。
- 全局设计文档：
docs/项目名称-技术栈设计.md 和 docs/项目结构设计.md（不存在则扫描同名文件，找不到不阻塞执行）。
- 原始设计文档：根据"设计文档溯源"中的文档名，读取
docs/功能设计/原始材料/[文档名].md 中与当前模块相关的章节。
- 契约索引：读取
docs/功能设计/_contracts.md，遍历已有条目与本模块做兼容性对比（依赖冲突、验收标准冲突、业务规则冲突）。若为项目首个模块（_contracts.md 不存在且 docs/功能设计/ 下无规格文档），跳过冲突检测。
- 已有意图文档（增量模式）：若
incremental_mode=design_docs_only_intent_draft，读取已存在的意图文档，提取已完成章节，作为续写起点。
执行流程
本 Skill 按四个连续步骤执行。每步完成后自然进入下一步——若步骤中发起 AskUserQuestion，框架会将用户答案回传后从断点继续。
步骤 1：意图澄清
目标：通过多轮迭代彻底澄清业务需求，直到所有关键维度无歧义。
-
收集全部输入材料。
-
增量模式判断：若 incremental_mode=design_docs_only_intent_draft 且意图文档已存在：
- 读取已有意图文档，识别已完成章节和未填写的章节。
- 从首个未完成章节开始续写，汇报"已完成的段落"和"待澄清的部分"。
- 对未完成部分进入澄清流程（跳至步骤 4）。
-
识别模块类型：
🔴 核心 → 核心澄清流程（步骤 4）🟢 一般 → 快速自检流程（步骤 5）
-
核心澄清流程：
- 汇报调研背景（3-5 句话）：材料清单、业务边界初步分析、兼容性审查结论。
- 识别当前最关键的 2-4 个未澄清维度：歧义点、未定义项、冲突点、业务规则、验收标准、边界权衡。
- 整理为具体问题，发起 AskUserQuestion。问题设计参考
references/confirmation-examples.md 中的问题框架模式——每个问题具体可回答，推荐方案标注优先，选项对比清晰。
-
快速自检流程（🟢 一般 模块）：
| 自检维度 | 通过标准 |
|---|
| 业务边界 | 设计文档已明确本模块的职责范围 |
| 输入/输出业务定义 | 业务字段可从设计文档直接推断 |
| 业务规则 | 使用行业默认规则或项目统一规范 |
| 状态机 | 无复杂异步流程，或状态转换已在设计文档中描述清楚 |
| 兼容性 | 与已有规格无业务冲突 |
自检结果分流：
- 5 项全部通过 → 发起 AskUserQuestion 请求快速授权（参考
references/confirmation-examples.md 示例 4 的问题框架）。
- 1-2 项未通过 → 针对未通过维度提出 1-2 个澄清问题（最多 1 轮），发起 AskUserQuestion。
- >=3 项未通过 → 切换回核心澄清流程。
后续轮次（用户回答 AskUserQuestion 后从断点继续）：
- 整合用户回答，更新"已澄清维度清单"。
- 判断终止条件（以下全部满足方可终止）：
- 所有歧义点已有确认解释
- 所有未定义项已有确认值或策略
- 所有冲突点已有裁决
- 所有业务规则已有明确方向
- 模块边界、输入/输出业务定义、状态机需求已无模糊
- 所有验收标准已有量化指标
- 已明确列出"留给规范阶段的技术决策"清单
- 终止条件未满足：基于剩余未澄清维度，整理下一轮 1-4 个问题，发起 AskUserQuestion。
- 终止条件已满足：本轮澄清完成。输出澄清共识摘要（3-5 条关键结论），自动进入步骤 2（书写授权）。
确认点问题设计原则：
- 每个问题必须具体、可回答，推荐方案放在最前并标注为推荐项。
- 在问题前用 3-5 句话简要汇报调研背景。
- 若有多项待确认内容，一次性全部列出。
- 参考
references/confirmation-examples.md 中的问题框架模式（提取问题设计逻辑，不照搬特定语法）。
步骤 2：书写授权
目标：汇总澄清共识，获得用户显式授权后进入文档生成。
- 读取输入材料及步骤 1 的所有澄清记录。
- 总结已达成的主要共识（每条一句话）：
- 业务边界
- 输入/输出的业务定义
- 状态机需求（如不适用则说明）
- 关键业务规则
- 验收标准（含关键量化指标）
- 确认"留给规范阶段的技术决策"清单已明确且内容非空。
- 发起 AskUserQuestion 请求书写授权。列出全部共识，选项为："授权"（确认共识，开始生成意图文档）、"继续澄清"（回到步骤 1 继续澄清）、"放弃模块"（放弃本模块设计）。问题设计参考
references/confirmation-examples.md 示例 5 的问题框架。
若用户选择"继续澄清"：回到步骤 1 继续澄清。
步骤 3：生成意图文档
前置条件：已通过步骤 2 获得书写授权。
目标：按模板生成意图文档（草稿状态）。
- 读取输入材料、步骤 1 的澄清记录和步骤 2 的授权记录。
- 按
references/intent-template.md 模板生成意图文档，文档状态为 草稿。
- 确保目标目录存在：
docs/功能设计/[序号]-[分组]/[编号]-[名称]/。
- 输出到：
docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-意图文档.md。
增量模式处理：若已有意图文档（incremental_mode=design_docs_only_intent_draft），在已有文档基础上更新/补全未完成章节，版本记录追加新行（如 v1.1），而非覆盖重写。
通用规则：
- 使用业务方可理解的语言，不出现具体技术类型（如 Pydantic、TypeScript 类型）。
- 每个业务字段包含：字段名、业务含义、是否必填、业务约束、示例值。
- 验收标准可量化、可测试。
- 状态使用业务名称，描述业务含义和进入/退出条件。
- 异常策略从业务角度描述，无技术处理细节。
- 必须包含"留给规范阶段的技术决策"章节且内容非空。
- 所有业务概念使用语义化命名，严禁使用模块编号作为命名前缀。
- 绝对禁止偷懒表述：
"等等"、"..."、"其他字段"、"类似"、"同上"、"请根据实际情况补充"。
禁止写入：具体技术类型、技术实现细节、技术选型理由、架构权衡、备选方案对比、编码层面的禁止行为。
版本记录格式约束：版本记录整体位于 Markdown 引用块内，每行以 > 开头。追加新版本行时，新行也必须以 > 开头。
将文档写入磁盘（使用 Write 工具写入上述路径），确认文件已落盘后进入步骤 4。
步骤 4：冻结授权
目标：获得用户显式冻结授权后锁定意图文档。这是整个意图编写流程最重要的门控节点——冻结后文档不可擅自修改。
- 读取已生成的意图文档。
- 总结文档核心内容（业务边界、验收标准、关键业务规则各一句话）。
- 明确告知用户"冻结后不可擅自修改，如需修改必须通过回退机制重新解冻"。
- 发起 AskUserQuestion 请求冻结授权，选项为："确认冻结"（锁定意图文档，进入规格阶段）、"冻结并进入契约协调"（跳过规格准备/预研/设计文档，直接进入契约协调，适用于 code_only 路径）、"重新澄清"（回到步骤 1 重新澄清业务需求）、"放弃模块"（放弃本模块设计）。问题设计参考
references/confirmation-examples.md 示例 6 的问题框架。
用户回答后：
- "确认冻结" 或 "冻结并进入契约协调"：
- 获取当前时间戳。
- 更新文档状态为
已冻结，写入冻结时间和版本记录行（新增 v2.0 行，状态标注 **已冻结**）。
- 保存修改后的文档。
- 上报 DONE。
- "重新澄清"：
- 根据用户反馈修改文档内容。
- 回到步骤 1 继续澄清。
- 版本记录追加修改行并更新版本号。
- "放弃模块"：
- 上报 DONE（模块放弃）。
质量检查清单
输出前逐项确认：
通用检查：
业务内容检查：
约束与禁止行为
- 禁止跳过澄清：
🔴 核心 模块必须经过步骤 1 多轮澄清，🟢 一般 模块必须经过快速自检。不得跳过澄清直接生成。
- 禁止越界决策：涉及业务矛盾或文档不足的问题，必须上报用户确认，禁止自行裁决。
- 禁止缺少技术决策留白：每份意图文档必须包含"留给规范阶段的技术决策"章节且内容非空。
- 禁止未授权生成：未通过步骤 2 书写授权前，不得进入步骤 3 生成文档。
- 禁止未冻结标记：未通过步骤 4 冻结授权前，不得将文档状态设为
已冻结。
- 禁止写入技术细节：意图文档中不得出现具体技术类型、技术实现细节、架构权衡、备选方案对比。
- 禁止偷懒表述：文档中不得出现
"等等"、"..."、"其他字段"、"类似"、"同上"、"请根据实际情况补充"。
- 禁止合并模块：每个模块独立输出一份意图文档，不得将多个功能点合并到同一份文档。
- 禁止逐字复制：不得逐字复制总设计的描述性段落。
参考文件索引
| 文件 | 归属 | 用途 | 加载时机 |
|---|
references/intent-template.md | Skill 独有 | 意图文档输出模板（完整结构与填写规范） | 步骤 3 生成文档 |
references/confirmation-examples.md | Skill 独有 | 确认问题设计参考（提取问题框架模式） | 步骤 1/2/4 确认点 |
