adspecs 0.1.12

package/skills/adspecs-new-requirement/SKILL.md

@@ -0,0 +1,608 @@
+---
+name: "adspecs-new-requirement"
+description: "基于业务需求描述，结合 01-业务需求分析模板（六步结构），完成深度需求分析并输出业务需求分析文档。Skill 内部执行模拟需求评审（多角色尖锐提问），评审结论融入最终决策。在写 PRD 之前，先搞清楚真正的问题是什么、为谁解决、怎么解决、有哪些风险。"
+argument-hint: "描述你要分析的业务需求，或指定已有需求文档路径"
+compatibility: "需要 docs/ 目录体系，含 01-业务需求分析模板.md"
+metadata:
+  author: "Qingwen Chen"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# 业务需求分析 (Business Requirement Analysis)
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+**必须** 在继续之前考虑用户输入（如果非空）。
+
+## 路径配置加载
+
+在开始执行之前，先确定输出目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键             | 默认值                          | 用途                                                       |
+| ------------------ | ------------------------------- | ---------------------------------------------------------- |
+| `biz_analysis_dir` | `docs/00-customer-requirements` | 业务需求分析文档输出目录                                   |
+| `architecture_dir` | `docs/10-architecture`          | 架构规划文档目录（用于读取业务功能架构文档，识别二级模块） |
+
+将解析后的路径记为 `OUTPUT_DIR` 和 `ARCH_DIR`，后续步骤中引用此变量而非硬编码路径。
+
+## 定位
+
+本 skill 专注于 **业务需求深度分析**，是产品交付流水线的第一步——在写 PRD（`02`-产品需求说明书）之前，先完成六步需求分析 + 模拟需求评审，确保方向正确。
+
+| 对比项   | adspecs-new-requirement（本 skill）                          | adspecs-prd                            | adspecs-front-spec           | adspecs-plan                  |
+| -------- | ------------------------------------------------------------ | -------------------------------------- | ---------------------------- | ----------------------------- |
+| 输出     | 业务需求分析（1 个文件）                                     | 产品需求说明书（1 个文件）             | 功能规格说明书（1 个文件）   | 系统设计 + SQL（2 个文件）    |
+| 模板     | `01-业务需求分析模板.md`                                     | `02-产品需求说明书模板.md`             | `04-前端功能设计模板.md`     | `03-系统设计模板.md`          |
+| 目标读者 | 产品经理、业务方、技术负责人                                 | 产品经理、业务方                       | 产品经理、前端开发、UX       | 开发架构师、后端工程师        |
+| 核心问题 | **为什么要做 & 问题本质是什么**                              | **做什么 & 为什么**                    | **怎么用**                   | **怎么建**                    |
+| 关注点   | 真实问题、解法空间、角色权限、流程状态、异常边界、需求成熟度 | 业务场景、用户故事、功能描述、验收标准 | 页面路由、界面布局、交互行为 | DO/DTO/VO、数据模型、接口设计 |
+
+**典型工作流**：
+
+1. 先用 `adspecs-new-requirement` 完成深度需求分析，确认方向正确（为什么做）
+2. 再用 `adspecs-prd` 生成产品需求说明书供业务方确认（做什么）
+3. 然后用 `adspecs-front-spec` 生成功能规格说明书确认交互细节（怎么用）
+4. 最后用 `adspecs-plan` 生成技术系统设计文档（怎么建）
+
+## 角色
+
+你是一位拥有 10 年经验的资深产品负责人，擅长复杂业务需求分析。你的核心能力是：
+
+- **透过现象看本质**：业务方说的需求往往不是真正的问题，你能通过追问挖掘真实痛点
+- **全局视角**：能从用户、技术、业务三个维度审视需求，不遗漏关键角色和场景
+- **风险嗅觉**：擅长在早期发现需求的盲点和风险，避免团队做无用功
+- **结构化思维**：将模糊的业务描述拆解为可分析、可验证的结构化文档
+
+## 任务
+
+读取用户提供的业务需求描述（或已有需求文档），按照七步分析法（六步写入文档 + 模拟评审内部执行）完成深度需求分析，输出业务需求分析文档。
+
+## 输入
+
+- **业务需求描述**: 用户在 `$ARGUMENTS` 中提供的文字描述，或指定的已有需求文档路径
+  - 可以是自然语言描述（如"我们需要一个客户管理模块"）
+  - 也可以是文件路径（如 `docs/00-customer-requirements/crm/客户需求.md`）
+  - 如果输入为空，提示用户输入需求描述
+- **模板文件**: `.adspecs/templates/01-业务需求分析模板.md` — 业务需求分析输出模板（六步结构）
+- **业务功能架构文档**: `{ARCH_DIR}/01-*_business_scenarios.md` 或 `{ARCH_DIR}/01-*_business_architecture.md` — 用于识别需求所属的二级模块（子模块）
+- **项目上下文**（可选）:
+  - `CLAUDE.md` — 项目技术架构、模块结构
+  - `docs/00-customer-requirements/` — 已有的客户需求文档
+  - `.adspecs/feature.json` — 已有功能追踪信息
+
+## 执行前检查
+
+**检查扩展钩子（业务需求分析前）**:
+
+- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.before_biz_analysis` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选前置钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+  - **必选钩子** (`optional: false`):
+
+    ```
+    ## 扩展钩子
+
+    **自动前置钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    等待钩子命令结果后再继续执行。
+    ```
+
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
+
+1. **解析用户输入**：
+   - 如果 `$ARGUMENTS` 是文件路径（以 `docs/` 或 `/` 开头，或以 `.md` 结尾）→ 读取该文件作为需求描述
+   - 如果 `$ARGUMENTS` 是自然语言描述 → 直接使用
+   - 如果 `$ARGUMENTS` 为空 → 使用 **AskUserQuestion** 工具提示用户输入需求描述
+
+2. **加载模板**：
+   - 读取 `.adspecs/templates/01-业务需求分析模板.md`，获取六步分析法的完整结构
+   - 如果模板不存在，使用内置的分析结构（见下方"七步分析法"，其中第六步为 skill 内部模拟评审，不写入模板）
+
+3. **加载项目上下文**（可选）：
+   - 如果 `CLAUDE.md` 存在，读取以了解项目背景
+   - 如果 `docs/00-customer-requirements/` 下有相关文档，读取以补充需求背景
+
+4. **识别二级模块**：
+   - 扫描 `{ARCH_DIR}/` 目录，查找 `01-*_business_scenarios.md` 或 `01-*_business_architecture.md` 文件（业务功能架构文档，两者命名均可能出现）
+   - 如果找到，读取文件内容，重点关注：
+     - **二、系统模块总览** → **2.2 子模块清单**：获取所有主模块（M00~M{N}）及其下属的二级模块（子模块，编号格式如 M03-01、M03-02、SYS-01 等）
+     - **三、各模块业务场景详述**：获取每个模块的业务场景描述（S-M{XX}-{YY} 系列）
+   - 将需求描述内容与各二级模块的名称、说明、业务场景进行语义匹配，确定需求最匹配的**二级模块编号**（如 M03-02）
+   - 匹配规则：
+     1. **精确匹配**：需求描述中明确提到某个子模块名称或编号 → 直接采用
+     2. **场景匹配**：需求描述的业务场景与某个模块下的场景（S-M{XX}-{YY}）高度吻合 → 采用该子模块编号
+     3. **语义匹配**：需求描述的核心功能与某个子模块的"说明"字段语义相近 → 采用该子模块编号
+     4. **无法匹配**：需求内容与任何二级模块都不匹配 → 使用 AskUserQuestion 让用户从二级模块列表中选择，或标记为"新模块"
+   - 将匹配到的二级模块编号记为 `MODULE_ID`（如 `M03-02`），对应的主模块编号记为 `PARENT_MODULE`（如 `M03`）
+   - 如果架构文档不存在，跳过此步骤，`MODULE_ID` 留空，输出目录不包含模块子目录
+
+5. **确定输出路径**：
+   - 输出根目录：`{OUTPUT_DIR}/`（由路径配置加载阶段解析，默认 `docs/00-customer-requirements/`）
+   - 如果 `MODULE_ID` 已识别（非空）：
+     - 输出子目录：`{OUTPUT_DIR}/{MODULE_ID}/`（如 `docs/00-customer-requirements/M03-02/`）
+     - 如果子目录不存在，自动创建
+   - 如果 `MODULE_ID` 为空（架构文档不存在或无法匹配）：
+     - 直接使用 `{OUTPUT_DIR}/` 作为输出目录（兼容旧行为）
+   - 输出文件名：基于需求描述生成简洁名称，格式 `{short-name}_业务需求分析.md`
+   - 完整输出路径示例：
+     - 有模块：`docs/00-customer-requirements/M03-02/customer-management_业务需求分析.md`
+     - 无模块：`docs/00-customer-requirements/customer-management_业务需求分析.md`
+   - 如果目录下已有同名文件，询问用户是覆盖还是重命名,还是新增版本号格式如下：
+     - 有模块：`docs/00-customer-requirements/M03-02/{MODULE_ID}_{short-name}_业务需求分析_v{version}.md`
+     - 无模块：`docs/00-customer-requirements/{short-name}_业务需求分析_v{version}.md`
+   - 将解析后的路径持久化到 `.adspecs/feature.json`（多功能注册表格式）：
+
+     ```json
+     {
+       "active": "<resolved feature dir>",
+       "requirement": [
+         {
+           "id": "<功能ID>",
+           "directory": "<resolved feature dir>",
+           "filename": "<resolved feature filename>",
+           "name": "<需求名称>",
+           "phase": "requirement",
+           "status": "drafting",
+           "created": "<DATE>"
+         }
+       ]
+     }
+     ```
+
+     **操作方式**:
+     1. 读取现有的 `.adspecs/feature.json`（如存在）
+     2. 将新功能追加到 `requirement` 数组（若 directory 已存在则跳过，避免重复）
+     3. 将 `active` 更新为当前功能目录
+     4. 写入文件（使用 2-space 缩进以保证可读性）
+
+     写入实际的解析后目录路径值（例如 `{OUTPUT_DIR}/003-user-auth`），而非字面字符串 `ADSPECS_FEATURE_DIRECTORY`。
+     这允许下游命令（`/adspecs-prd` 等）通过 `active` 字段定位当前功能目录，而无需依赖 git 分支名称约定。
+
+     **注意**: 不要在功能目录下创建 `feature.json` 文件——所有功能追踪统一在 `.adspecs/feature.json` 中管理。
+
+## 七步分析法
+
+> **注意**：模板 `01-业务需求分析模板.md` 包含六步结构（一~六）。本 skill 在六步基础上额外执行**第六步·模拟需求评审**（skill 内部分析），评审结论融入第七步最终决策。输出文档按模板的六步结构组织，评审发现体现在「最终输出与决策」的风险和成熟度评估中。
+
+### 一、真实问题分析
+
+**目标**：搞清楚业务方真正想解决的问题，避免做错方向。
+
+**分析步骤**：
+
+1. **记录表面需求**：业务方原话描述的需求是什么？不加翻译，原样记录。
+
+2. **3 层 Why 追问**：
+   - 第 1 层：为什么需要这个功能？→ 挖掘直接原因
+   - 第 2 层：为什么这个问题现在必须解决？→ 挖掘紧迫性和背景
+   - 第 3 层：如果不解决，最严重的后果是什么？→ 挖掘影响和风险
+
+3. **总结真实问题**：用一句话概括真正要解决的问题。
+
+4. **解法空间分析**：
+   - 列出至少 2-3 种可能的解决方案（包括业务方提议的方案）
+   - 对每种方案评估优势、劣势和可行性
+   - 给出选定方案及理由
+
+**输出要求**：
+
+- 如果需求描述中有明显的"方案倾向"（业务方直接说"我要一个 XX 功能"），必须追问真实问题
+- 如果表面需求和真实问题不一致，明确标注差异
+- 不确定的部分标注 `[待确认：具体问题]`，最多 3 个
+
+### 二、用户角色分析
+
+**目标**：明确涉及哪些角色、每个角色的诉求和权限边界。
+
+**分析步骤**：
+
+1. **角色识别**：从需求描述中提取所有涉及的用户角色（包括直接使用和间接影响的角色）
+
+2. **角色画像**：对每个角色分析：
+   - 使用目标：想通过系统达成什么？
+   - 关注信息：最关心看到什么数据/状态？
+   - 使用频率：每天/每周/偶尔？
+
+3. **权限矩阵**：梳理每个角色对核心操作的权限（可创建/可查看/可审批/可删除等）
+
+**输出要求**：
+
+- 至少识别 2 个角色（操作者 + 管理者/审批者是最低要求）
+- 权限矩阵必须覆盖核心操作
+- 如果角色之间的权限边界不清晰，标注 `[待确认：角色权限边界]`
+
+### 三、使用场景拆解
+
+**目标**：把需求拆成具体的使用场景，确定优先级。
+
+**分析步骤**：
+
+1. **场景列举**：用户在什么情况下会使用？列出所有可识别的场景
+
+2. **场景分类**：
+   - 高频场景：用户日常操作的主路径
+   - 低频但重要场景：如批量操作、异常处理、数据导出等
+   - 可延后场景：体验优化类
+
+3. **优先级判定**（按 "频率 × 影响面 × 不可替代性" 判断）：
+   - P0（必须支持）：高频 + 核心业务路径
+   - P1（应当支持）：中频或低频但有合规/安全要求
+   - P2（可以延后）：低频且体验优化类
+
+**输出要求**：
+
+- 至少 4 个场景
+- 每个场景标注触发条件（用户什么时候会用到）
+- 明确 P0 场景，这些是后续 PRD 的核心
+
+### 四、业务流程梳理
+
+**目标**：把核心场景拆成完整的操作步骤，明确状态流转。
+
+**分析步骤**：
+
+1. **主流程（Happy Path）**：以最重要的 P0 场景为例，按步骤输出：
+   - 操作者（谁触发）
+   - 动作（做什么）
+   - 系统判断（需要校验什么）
+   - 输入/输出
+   - 状态变化
+
+2. **状态机**：梳理涉及的业务状态和流转规则
+   - 当前状态 → 触发事件 → 目标状态
+   - 每个流转的前置条件/约束
+
+3. **其他场景流程**：对其他 P0/P1 场景补充流程（可仅标注与主流程的差异）
+
+**输出要求**：
+
+- 主流程至少 4 个步骤
+- 状态机至少包含 3 个状态
+- 如果流程涉及多角色协作（如提交→审批），必须明确交接点
+
+### 五、异常和边界场景
+
+**目标**：穷举可能遗漏的异常场景，防止上线后出问题。
+
+**分析步骤**：
+
+从以下 8 个角度逐一检查：
+
+| 角度     | 检查要点                       |
+| -------- | ------------------------------ |
+| 用户操作 | 重复提交、误操作、中途放弃     |
+| 系统状态 | 服务不可用时的降级策略         |
+| 数据     | 数据为空、超大数据量、格式错误 |
+| 权限     | 越权操作、权限变更后的影响     |
+| 网络     | 弱网/断网、请求超时            |
+| 并发     | 多人同时操作同一记录           |
+| 历史数据 | 旧数据不兼容新规则             |
+| 后台处理 | 异步任务超时/失败              |
+
+同时列出关键输入字段的边界值（最小值、最大值、特殊值、为空时行为）。
+
+**输出要求**：
+
+- 至少覆盖 5 个异常场景
+- 每个异常场景给出预期系统行为
+- 不确定的异常处理标注 `[待确认：异常处理策略]`
+
+### 六、需求评审
+
+**目标**：提前暴露需求盲点，减少后续返工。
+
+**分析步骤**：
+
+分别扮演三个角色提出尖锐问题：
+
+1. **资深研发视角**（关注技术可行性、性能、系统复杂度）：
+   - 这个功能对现有系统架构有什么影响？
+   - 数据量大了之后性能怎么保证？
+   - 有没有更轻量的实现方式？
+
+2. **测试负责人视角**（关注可测试性、验收标准、边界覆盖）：
+   - 验收标准够不够明确？怎么算"做完了"？
+   - 异常场景覆盖全了吗？
+   - 测试数据怎么准备？
+
+3. **业务负责人视角**（关注业务价值、投入产出比、上线时机）：
+   - 上线后预期带来什么业务指标提升？
+   - 用户习惯改变成本高吗？
+   - 如果不做，最坏的结果是什么？
+
+对每个问题给出评审结论（已解决 / 待补充）和后续行动项。
+
+**输出要求**：
+
+- 每个角色至少 2 个尖锐问题
+- 问题必须基于当前需求分析的具体内容，不能是泛泛的模板问题
+- 评审结论表汇总所有问题的解决状态
+
+### 七、最终输出与决策
+
+**目标**：通过 10 项质量检查验证分析完整性，给出需求成熟度判断和下一步建议。
+
+**分析步骤**：
+
+1. **需求分析质量检查（10 项）**：逐项验证分析是否到位，每项标注 ✅ 已覆盖 / ⚠️ 部分覆盖 / ❌ 未覆盖，并关联到对应的分析章节：
+
+   | #   | 检查项                         | 状态     | 对应章节   | 补充说明                                                 |
+   | --- | ------------------------------ | -------- | ---------- | -------------------------------------------------------- |
+   | 1   | 这个需求解决的真实问题是什么？ | ✅/⚠️/❌ | 一·1.2     | 【真实问题是否已用 3 层 Why 锁定】                       |
+   | 2   | 业务方给的是问题，还是方案？   | ✅/⚠️/❌ | 一·1.1/1.3 | 【是否区分了表面需求和真实问题，是否评估了多种解法】     |
+   | 3   | 核心用户角色是谁？             | ✅/⚠️/❌ | 二·2.1     | 【主要操作者是否已识别，目标和频率是否明确】             |
+   | 4   | 还有哪些相关角色会被影响？     | ✅/⚠️/❌ | 二·2.1/2.2 | 【间接影响的角色（审批者、管理者、下游系统）是否已考虑】 |
+   | 5   | 用户在什么场景下使用？         | ✅/⚠️/❌ | 三·3.1     | 【高频+低频场景是否已拆解，触发条件是否明确】            |
+   | 6   | 完整业务流程是什么？           | ✅/⚠️/❌ | 四·4.1     | 【主流程每一步的操作者、动作、输入输出是否清晰】         |
+   | 7   | 每一步涉及哪些状态变化？       | ✅/⚠️/❌ | 四·4.2     | 【状态机是否已梳理，流转条件和约束是否明确】             |
+   | 8   | 有哪些异常和边界场景？         | ✅/⚠️/❌ | 五·5.1     | 【是否从操作/系统/数据/权限/网络/并发等多角度覆盖】      |
+   | 9   | 研发、测试可能会质疑什么？     | ✅/⚠️/❌ | 六（评审） | 【模拟评审是否提出了有针对性的尖锐问题】                 |
+   | 10  | 上线后用什么指标判断有效？     | ✅/⚠️/❌ | 六·6.2     | 【是否定义了可度量的成功标准（业务指标/性能指标）】      |
+
+2. **通过规则**：
+   - **✅ 全部通过**：10 项均为 ✅ → 建议进入 PRD 阶段
+   - **⚠️ 基本通过**：存在 ⚠️ 但无 ❌ → 标注需补充的具体项，补充后可进入 PRD
+   - **❌ 未通过**：存在任意 ❌ → 列出缺失项，建议进一步调研后重新分析
+
+3. **风险与待补充**：基于检查项中 ⚠️ 和 ❌ 的结果，汇总最大风险和待补充信息
+
+4. **决策建议**（三选一）：
+   - ✅ 需求清晰（10/10 通过），建议进入 `02`-产品需求说明书（PRD）阶段
+   - ⚠️ 需求基本清晰（{N}/10 通过），补充以下信息后可进入 PRD 阶段
+   - ❌ 需求不够清晰（{N}/10 通过），需要进一步调研后重新分析
+
+## 工作流程
+
+### 步骤 1：解析输入并加载上下文
+
+1. 解析 `$ARGUMENTS`：
+   - 文件路径 → 读取文件内容作为需求描述
+   - 自然语言 → 直接使用
+   - 空 → 使用 **AskUserQuestion** 提示用户输入
+
+2. 加载模板 `.adspecs/templates/01-业务需求分析模板.md`
+
+3. 加载项目上下文（`CLAUDE.md`、已有需求文档等）
+
+4. **识别二级模块**：
+   - 扫描 `{ARCH_DIR}/` 目录，查找 `01-*_business_scenarios.md` 或 `01-*_business_architecture.md`
+   - 如果找到，读取并按"执行前检查 · 步骤 4"的规则匹配二级模块编号 `MODULE_ID`
+   - 如果未找到或无法自动匹配，按规则处理（用户选择或留空）
+
+### 步骤 2：执行七步分析
+
+按"七步分析法"逐节完成分析。其中第一~五步和第七步写入输出文档，第六步（需求评审）为 skill 内部分析，评审结论融入第七步的决策。每一节的执行要求：
+
+1. **先读模板对应章节**：了解该节需要的输出格式和字段
+2. **分析需求描述**：从用户输入中提取相关信息
+3. **补充推理**：基于上下文和行业标准做出合理推断
+4. **标注不确定项**：用 `[待确认：具体问题]` 标注，**全文最多 3 个**
+5. **填入模板格式**：按模板的表格/列表格式输出
+
+**关键原则**：
+
+- 不要急着给方案，先分析问题本质
+- 每一步的分析结论必须有依据（来自用户输入、项目上下文或合理推断）
+- 如果用户输入信息不足以完成某一节，基于合理推断填写并标注 `[待确认]`
+- 模拟需求评审（第六步）的问题必须基于前 5 步的分析结果，提出有针对性的尖锐问题
+
+### 步骤 3：写入分析文档
+
+1. **确定输出文件路径**：
+
+   ```
+   OUTPUT_DIR = 路径配置加载阶段解析的值（默认 `docs/00-customer-requirements`）
+   MODULE_ID  = 识别到的二级模块编号（如 M03-02），可能为空
+
+   # 有模块编号时：
+   OUTPUT_FILE = "{OUTPUT_DIR}/{MODULE_ID}/{MODULE_ID}_{short-name}_{createdate}_业务需求分析.md"
+   # 示例：docs/00-customer-requirements/M03-02/M03-02_customer-management_20260607_业务需求分析.md
+
+   # 无模块编号时（兼容旧行为）：
+   OUTPUT_FILE = "{OUTPUT_DIR}/{short-name}_{createdate}_业务需求分析.md"
+   # 示例：docs/00-customer-requirements/customer-management_20260607_业务需求分析.md
+   ```
+
+   - `MODULE_ID`：识别到的二级模块编号（如 `M03-02`、`SYS-04`）。如果目录不存在则自动创建
+   - `short-name`：从需求描述中提取 2-4 个词的简洁名称（如 `customer-management`、`order-approval`）
+
+2. **写入文件**：使用 Write 工具将完整的分析文档写入 `OUTPUT_FILE`
+   - 文档头部填写模块编号（`MODULE_ID`）、主模块编号（`PARENT_MODULE`）、模块名称、日期等元信息
+   - 按模板结构输出六步分析结果（模拟需求评审的发现融入第六步的风险评估）
+   - 保留模板中的表格格式和章节结构
+
+3. **输出确认信息**：
+   ```
+   ✅ 业务需求分析完成
+   所属模块：{PARENT_MODULE} > {MODULE_ID}
+   输出文件：{OUTPUT_FILE}
+   质量检查：{N}/10 通过
+   下一步建议：{决策建议}
+   ```
+
+### 步骤 4：质量检查输出
+
+执行 10 项需求分析质量检查（定义在"七、最终输出与决策"中）：
+
+1. **逐项验证**：对照 10 项检查清单，逐项标注 ✅/⚠️/❌，并填写补充说明
+2. **关联回溯**：每项检查必须关联到输出文档中对应章节的具体内容，确认不是空占位符
+3. **汇总判定**：
+   - 10 项均 ✅ → 决策为"建议进入 PRD"
+   - 有 ⚠️ 无 ❌ → 决策为"补充后可进入 PRD"，列出需补充的项
+   - 有 ❌ → 决策为"需进一步调研"，列出缺失的项和调研方向
+
+### 步骤 5：后续建议
+
+根据质量检查结果（10 项检查清单），给出明确的下一步建议：
+
+- **如果 ✅ 10/10 通过**：
+
+  ```
+  📋 建议下一步执行：/adspecs-prd {需求概要}
+  ```
+
+- **如果 ⚠️ N/10 通过（有 ⚠️ 无 ❌）**：
+
+  ```
+  ⚠️ 在写 PRD 之前，建议先补充以下信息：
+  1. {未通过的检查项对应的待补充内容}
+  2. {待补充项 2}
+  ```
+
+- **如果 ❌ N/10 通过（有 ❌）**：
+  ```
+  ❌ 需求分析显示当前信息不够清晰，建议：
+  1. {未通过的检查项对应的调研方向}
+  2. {调研方向 2}
+  补充后可重新执行 /adspecs-new-requirement
+  ```
+
+## 必选执行后钩子
+
+**必须在向用户报告完成之前完成本节。**
+
+检查项目根目录是否存在 `.adspecs/extensions.yml`。
+
+- 如果不存在，或 `hooks.after_biz_analysis` 下没有注册钩子，跳到完成报告。
+- 如果存在，读取它并查找 `hooks.after_biz_analysis` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**：
+
+    ```
+    ## 扩展钩子
+
+    **自动钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+
+  - **可选钩子** (`optional: true`):
+
+    ```
+    ## 扩展钩子
+
+    **可选钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+
+## 输出文件结构
+
+> 输出文档按模板的**六步结构**组织。模拟需求评审（skill 内部第七步）的发现融入「六、最终输出与决策」的风险评估和成熟度判断中，不单独成节。
+
+```markdown
+# 01-业务需求分析：{模块名称}
+
+> **版本**: v1.0
+> **创建日期**: {today}
+> **主模块**: {PARENT_MODULE} {主模块名称}
+> **二级模块编号**: {MODULE_ID}
+> **二级模块名称**: {模块名称}
+> **需求来源**: {来源}
+
+| 项           | 值                           |
+| ------------ | ---------------------------- |
+| 主模块       | {PARENT_MODULE} {主模块名称} |
+| 二级模块编号 | {MODULE_ID}                  |
+| 二级模块名称 | {模块名称}                   |
+| 阶段         | Proposal（Why → What 过渡）  |
+| 下游         | → 02-产品需求说明书          |
+
+---
+
+## 一、真实问题分析
+
+### 1.1 表面需求
+
+### 1.2 真实问题（3层Why追问）
+
+### 1.3 解法空间
+
+## 二、用户角色分析
+
+### 2.1 角色清单
+
+### 2.2 权限矩阵
+
+## 三、使用场景拆解
+
+### 3.1 场景清单
+
+### 3.2 优先级判定
+
+## 四、业务流程梳理
+
+### 4.1 主流程（Happy Path）
+
+### 4.2 状态机
+
+### 4.3 其他场景流程
+
+## 五、异常和边界场景
+
+### 5.1 异常场景清单
+
+### 5.2 边界值检查
+
+## 六、最终输出与决策
+
+### 6.1 需求分析质量检查（10 项）
+
+### 6.2 风险与待补充（含评审发现）
+
+### 6.3 决策
+
+## 附录：与 02 产品需求说明书的关系
+```
+
+## 完成标志
+
+- [ ] 已解析用户输入（需求描述或文档路径）
+- [ ] 已加载 01-业务需求分析模板
+- [ ] 已扫描 `{ARCH_DIR}/` 并识别匹配的二级模块编号 `MODULE_ID`（或确认为空/用户手动选择）
+- [ ] 七步分析全部完成（真实问题、角色、场景、流程、异常、模拟评审、决策）
+- [ ] 模拟需求评审已在 skill 内部执行（研发/测试/业务三角色提问）
+- [ ] 评审发现已融入「六、最终输出与决策」的风险评估中
+- [ ] 10 项质量检查已逐项验证（真实问题 / 问题vs方案 / 核心角色 / 相关角色 / 使用场景 / 业务流程 / 状态变化 / 异常边界 / 研发测试质疑 / 上线指标）
+- [ ] 分析文档已按模板六步结构写入 `{OUTPUT_DIR}/{MODULE_ID}/{MODULE_ID}_{name}_业务需求分析.md`（无模块时写入 `{OUTPUT_DIR}/{name}_业务需求分析.md`）
+- [ ] 质量检查结果（N/10）和下一步建议已输出
+- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过