module-intent-writer

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

输入材料收集（按需）

在执行具体步骤前，从以下来源收集材料。仅读取当前模块相关的内容，不再扫描全部模块：

1. 功能模块全拆解表：docs/功能设计/功能模块全拆解.md，定位当前模块所在行，提取核心功能、颗粒度描述、设计文档溯源。
2. 全局设计文档：docs/项目名称-技术栈设计.md 和 docs/项目结构设计.md（不存在则扫描同名文件，找不到不阻塞执行）。
3. 原始设计文档：根据"设计文档溯源"中的文档名，读取 docs/功能设计/原始材料/[文档名].md 中与当前模块相关的章节。
4. 契约索引：读取 docs/功能设计/_contracts.md，遍历已有条目与本模块做兼容性对比（依赖冲突、验收标准冲突、业务规则冲突）。若为项目首个模块（_contracts.md 不存在且 docs/功能设计/ 下无规格文档），跳过冲突检测。
5. 已有意图文档（增量模式）：若 incremental_mode=design_docs_only_intent_draft，读取已存在的意图文档，提取已完成章节，作为续写起点。

执行流程

本 Skill 按四个连续步骤执行。每步完成后自然进入下一步——若步骤中发起 AskUserQuestion，框架会将用户答案回传后从断点继续。

步骤 1：意图澄清

目标：通过多轮迭代彻底澄清业务需求，直到所有关键维度无歧义。

1. 收集全部输入材料。

2. 增量模式判断：若 incremental_mode=design_docs_only_intent_draft 且意图文档已存在：

   • 读取已有意图文档，识别已完成章节和未填写的章节。
   • 从首个未完成章节开始续写，汇报"已完成的段落"和"待澄清的部分"。
   • 对未完成部分进入澄清流程（跳至步骤 4）。

3. 识别模块类型：

   • 🔴 核心 → 核心澄清流程（步骤 4）
   • 🟢 一般 → 快速自检流程（步骤 5）

4. 核心澄清流程：

   • 汇报调研背景（3-5 句话）：材料清单、业务边界初步分析、兼容性审查结论。
   • 识别当前最关键的 2-4 个未澄清维度：歧义点、未定义项、冲突点、业务规则、验收标准、边界权衡。
   • 整理为具体问题，发起 AskUserQuestion。问题设计参考 references/confirmation-examples.md 中的问题框架模式——每个问题具体可回答，推荐方案标注优先，选项对比清晰。

5. 快速自检流程（🟢 一般 模块）：

   自检维度	通过标准
   业务边界	设计文档已明确本模块的职责范围
   输入/输出业务定义	业务字段可从设计文档直接推断
   业务规则	使用行业默认规则或项目统一规范
   状态机	无复杂异步流程，或状态转换已在设计文档中描述清楚
   兼容性	与已有规格无业务冲突

   自检结果分流：

   • 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. 读取输入材料及步骤 1 的所有澄清记录。
2. 总结已达成的主要共识（每条一句话）：
   • 业务边界
   • 输入/输出的业务定义
   • 状态机需求（如不适用则说明）
   • 关键业务规则
   • 验收标准（含关键量化指标）
3. 确认"留给规范阶段的技术决策"清单已明确且内容非空。
4. 发起 AskUserQuestion 请求书写授权。列出全部共识，选项为："授权"（确认共识，开始生成意图文档）、"继续澄清"（回到步骤 1 继续澄清）、"放弃模块"（放弃本模块设计）。问题设计参考 references/confirmation-examples.md 示例 5 的问题框架。

若用户选择"继续澄清"：回到步骤 1 继续澄清。

步骤 3：生成意图文档

前置条件：已通过步骤 2 获得书写授权。

目标：按模板生成意图文档（草稿状态）。

1. 读取输入材料、步骤 1 的澄清记录和步骤 2 的授权记录。
2. 按 references/intent-template.md 模板生成意图文档，文档状态为 草稿。
3. 确保目标目录存在：docs/功能设计/[序号]-[分组]/[编号]-[名称]/。
4. 输出到：docs/功能设计/[序号]-[分组]/[编号]-[名称]/[编号]-[名称]-意图文档.md。

增量模式处理：若已有意图文档（incremental_mode=design_docs_only_intent_draft），在已有文档基础上更新/补全未完成章节，版本记录追加新行（如 v1.1），而非覆盖重写。

通用规则：

• 使用业务方可理解的语言，不出现具体技术类型（如 Pydantic、TypeScript 类型）。
• 每个业务字段包含：字段名、业务含义、是否必填、业务约束、示例值。
• 验收标准可量化、可测试。
• 状态使用业务名称，描述业务含义和进入/退出条件。
• 异常策略从业务角度描述，无技术处理细节。
• 必须包含"留给规范阶段的技术决策"章节且内容非空。
• 所有业务概念使用语义化命名，严禁使用模块编号作为命名前缀。
• 绝对禁止偷懒表述："等等"、"..."、"其他字段"、"类似"、"同上"、"请根据实际情况补充"。

禁止写入：具体技术类型、技术实现细节、技术选型理由、架构权衡、备选方案对比、编码层面的禁止行为。

版本记录格式约束：版本记录整体位于 Markdown 引用块内，每行以 > 开头。追加新版本行时，新行也必须以 > 开头。

将文档写入磁盘（使用 Write 工具写入上述路径），确认文件已落盘后进入步骤 4。

步骤 4：冻结授权

目标：获得用户显式冻结授权后锁定意图文档。这是整个意图编写流程最重要的门控节点——冻结后文档不可擅自修改。

1. 读取已生成的意图文档。
2. 总结文档核心内容（业务边界、验收标准、关键业务规则各一句话）。
3. 明确告知用户"冻结后不可擅自修改，如需修改必须通过回退机制重新解冻"。
4. 发起 AskUserQuestion 请求冻结授权，选项为："确认冻结"（锁定意图文档，进入规格阶段）、"冻结并进入契约协调"（跳过规格准备/预研/设计文档，直接进入契约协调，适用于 code_only 路径）、"重新澄清"（回到步骤 1 重新澄清业务需求）、"放弃模块"（放弃本模块设计）。问题设计参考 references/confirmation-examples.md 示例 6 的问题框架。

用户回答后：

• "确认冻结" 或 "冻结并进入契约协调"：
  1. 获取当前时间戳。
  2. 更新文档状态为 已冻结，写入冻结时间和版本记录行（新增 v2.0 行，状态标注 **已冻结**）。
  3. 保存修改后的文档。
  4. 上报 DONE。
• "重新澄清"：
  1. 根据用户反馈修改文档内容。
  2. 回到步骤 1 继续澄清。
  3. 版本记录追加修改行并更新版本号。
• "放弃模块"：
  1. 上报 DONE（模块放弃）。

质量检查清单

输出前逐项确认：

通用检查：

• 🔴 核心 模块：已通过步骤 1 多轮问答澄清所有关键决策点；🟢 一般 模块：已通过快速自检或最多 1 轮澄清
• 步骤 2 已获得用户显式书写授权
• 步骤 4 已获得用户显式冻结授权
• 文档已标注冻结状态和时间（仅冻结后）
• 文档包含"留给规范阶段的技术决策"章节且内容非空
• 所有"（待确认）"标注都有合理推断
• 已通过契约索引审查已有规格，无冲突或冲突已记录解决方案
• 已读取并参考项目技术栈设计文档和项目结构设计文档
• 版本记录每一行都以 > 开头

业务内容检查：

• 项目定位清晰，2-3 句话讲清模块业务角色与价值
• 用户旅程完整，涵盖主要使用场景
• 输入/输出字段的业务含义明确，无技术类型混入
• 验收标准可量化、可测试
• 业务约束清单有具体条目，不是空洞口号
• 异常策略从业务角度描述，无技术处理细节
• 状态定义使用业务名称，描述业务含义
• 未逐字复制总设计的描述性段落
• 无偷懒表述

约束与禁止行为

• 禁止跳过澄清：🔴 核心 模块必须经过步骤 1 多轮澄清，🟢 一般 模块必须经过快速自检。不得跳过澄清直接生成。
• 禁止越界决策：涉及业务矛盾或文档不足的问题，必须上报用户确认，禁止自行裁决。
• 禁止缺少技术决策留白：每份意图文档必须包含"留给规范阶段的技术决策"章节且内容非空。
• 禁止未授权生成：未通过步骤 2 书写授权前，不得进入步骤 3 生成文档。
• 禁止未冻结标记：未通过步骤 4 冻结授权前，不得将文档状态设为 已冻结。
• 禁止写入技术细节：意图文档中不得出现具体技术类型、技术实现细节、架构权衡、备选方案对比。
• 禁止偷懒表述：文档中不得出现 "等等"、"..."、"其他字段"、"类似"、"同上"、"请根据实际情况补充"。
• 禁止合并模块：每个模块独立输出一份意图文档，不得将多个功能点合并到同一份文档。
• 禁止逐字复制：不得逐字复制总设计的描述性段落。

参考文件索引

文件	归属	用途	加载时机
references/intent-template.md	Skill 独有	意图文档输出模板（完整结构与填写规范）	步骤 3 生成文档
references/confirmation-examples.md	Skill 独有	确认问题设计参考（提取问题框架模式）	步骤 1/2/4 确认点