---
name: "ads-write-sow"
description: "根据项目信息、合同要点与实施范围创建或更新工作说明书（SOW）。"
agent_created: true
argument-hint: "描述项目背景、甲乙方、实施范围与关键约定"
compatibility: "需要 adspecs 项目结构及 docs/ 目录"
metadata:
  author: "Qingwen Chen"
user-invocable: true
disable-model-invocation: false
---

## 用户输入

```text
$ARGUMENTS
```

**必须** 在继续之前考虑用户输入（如果非空）。

## 路径配置加载

在开始执行之前，先确定输出目录：

1. 检查项目根目录是否存在 `.adspecs/paths.json`
2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
3. 如果不存在或配置键缺失，使用下方表格中的默认值

| 配置键         | 默认值                 | 用途                                           |
| -------------- | ---------------------- | ---------------------------------------------- |
| `sow_dir`      | `docs/00-planning/sow` | 工作说明书（SOW）输出目录                      |
| `planning_dir` | `docs/00-planning`     | 规划阶段文档目录（输入解析时引用已有规划报告） |

将解析后的路径分别记为 `SOW_DIR` 和 `PLANNING_DIR`，后续步骤中引用此变量而非硬编码路径。

## 执行前检查

**检查扩展钩子（编写 SOW 前）**:

- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
- 如果存在，读取它并查找 `hooks.before_write_sow` 下的条目。
- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/ads-git-commit`。
- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
  - **可选钩子** (`optional: true`):

    ```
    ## 扩展钩子

    **可选前置钩子**: {extension}
    命令: `/{command}`
    描述: {description}

    提示: {prompt}
    执行: `/{command}`
    ```

  - **必选钩子** (`optional: false`):

    ```
    ## 扩展钩子

    **自动前置钩子**: {extension}
    执行: `/{command}`
    EXECUTE_COMMAND: {command}

    等待钩子命令结果后再继续执行。
    ```

- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。

## 概述

用户在触发消息中 `/ads-write-sow` 之后输入的文本**就是**项目与 SOW 描述。假设你在本次对话中始终可以获取到它，即使 `$ARGUMENTS` 字面上出现在下方。除非用户提供了空命令，否则不要要求用户重复输入。

SOW（工作说明书）是**项目级合同/配套文件**，用于定义乙方为甲方实施项目的工作内容、范围、计划、组织职责、假设约定与验收标准。与 PRD 不同，SOW **不是**按功能特性拆分的开发文档，因此本技能不使用 `feature.json` 功能注册流程，而是按项目生成单一 SOW 文档。

## 输入解析流程

1. **检查已有文档**：扫描 `{PLANNING_DIR}/`（默认 `docs/00-planning/`）是否已有 planning-report 报告；如有，读取其中的项目背景、目标、实施范围、模块清单、分期策略等，作为 SOW 编写的权威输入来源，避免重复采集。
2. **提取关键要素**：从用户输入与 planning-report 中识别甲方/乙方、项目名称、实施范围（模块/功能/集成/数据转换/客制化）、项目周期与里程碑、质保与验收要求。
3. **检查已有 SOW**：扫描 `{SOW_DIR}/` 是否已存在目标 SOW 文件；如有则进入**更新模式**，保留用户已确认内容，仅补全或修订缺失章节。
4. **做出合理推断**：对通用合同条款（问题分级、确认时限、办公模式、工作时间、SLA）沿用模板默认值，并将假设写入“关键假设条件”章节。对未明确的可选信息，基于行业标准和业务上下文推断其合理取值。
5. **标记待澄清项**：仅对显著影响**合同主体/范围/付款验收**的关键决策标记 [NEEDS CLARIFICATION]（最多 3 个）。

## 输出生成流程

根据项目描述，执行以下操作：

1. **生成简洁的项目短名称**（2-4 个词）用于文件命名：
   - 从描述中提取甲方简称、系统/产品名或项目关键词
   - 尽量使用 `客户简称-系统名` 形式（如 `abc-srm`、`xingye-crm`）
   - 保留行业术语与缩写（SRM、CRM、ERP、MES、WMS 等）
   - 示例：
     - "为 ABC 公司实施 SRM 系统" → "abc-srm"
     - "兴业 CRM 项目工作说明书" → "xingye-crm"
     - "XX 集团 MES 一期实施" → "xx-mes-phase1"

2. **创建 SOW 目录和文件**:

   SOW 默认存储在 `{SOW_DIR}` 目录下，除非用户明确提供了 `SOW_OUTPUT_DIRECTORY`。

   **`SOW_FILE` 的解析规则**:
   1. 如果用户明确提供了 `SOW_OUTPUT_DIRECTORY`（例如通过参数或配置），使用它作为输出目录
   2. 否则使用 `{SOW_DIR}` 作为输出目录
   3. 文件名规则：
      - 若识别到项目短名称：`{输出目录}/工作说明书SOW-<short-name>.md`
      - 否则：`{输出目录}/工作说明书SOW.md`
   4. 设置 `SOW_FILE` 为最终解析后的完整路径

   **创建目录和 SOW 文件**:
   - `mkdir -p {输出目录}`
   - 将 `.adspecs/templates/20-工作说明书SOW模板.md` 复制到 `SOW_FILE` 作为起点
   - 如果模板文件不存在，直接依据本技能末尾《SOW 章节结构》生成同等结构的文档

   **重要**:
   - 每次 `/ads-write-sow` 调用只生成或更新一个 SOW 文档
   - 若 `SOW_FILE` 已存在，进入**更新模式**：保留用户已填写的实际内容，仅补全或修订缺失章节，切勿用占位符覆盖已确认信息

3. 加载 `.adspecs/templates/20-工作说明书SOW模板.md` 以了解所需的结构（若不存在，使用本技能末尾《SOW 章节结构》作为权威结构）。

4. 遵循以下执行流程：
   1. 从参数中解析项目描述
      如果为空：错误 "No project / SOW description provided"
   2. 提取描述中的关键要素：
      - 甲方、乙方全称与简称
      - 项目名称、系统/产品范围（模块、功能、集成、数据转换、客制化）
      - 实施地点与办公模式
      - 项目周期、里程碑、需求冻结时间
      - 质保服务与 SLA 约定
      - 交付物与验收方式
   3. 对于不明确的方面：
      - 基于行业惯例与模板默认条款做出合理推断（如集中办公、5×8 工作时间、S/A/B/C 问题分级、5 工作日确认视为接受等）
      - 仅在以下情况标记为 [NEEDS CLARIFICATION: 具体问题]：
        - 该选择显著影响**合同范围、付款条件或验收责任**
        - 存在多种合理解释且法律/商务含义不同
        - 没有合理的默认值（如甲乙方主体、合同编号、实施范围边界）
      - **限制：最多 3 个 [NEEDS CLARIFICATION] 标记**
      - 按影响排序澄清优先级：合同主体/范围 > 付款与验收条件 > 计划与里程碑 > 服务细节
   4. 填写封面信息、文档修改记录、审批签字与保密声明
   5. 填写各正文章节（前言、项目综述、项目范围、项目计划、项目组织及职责、关键假设与约定、项目验收、附录A）
   6. 对涉及金额、周期、数量的空缺，保留 `[XX]` 占位并在《待补充信息清单》中汇总，供商务/项目经理确认
   7. 返回：成功（SOW 可进入双方评审与签署流程）

5. 使用模板结构将 SOW 写入 `SOW_FILE`，用从项目描述派生的具体细节替换占位符，同时保留章节顺序、编号和标题。

6. **SOW 质量验证**: 在编写初始 SOW 后，根据质量标准对其进行验证：

   a. **创建 SOW 质量检查清单**: 在 `{输出目录}/checklists/sow_checklist.md` 生成检查清单文件（多 SOW 时文件名追加 `-<short-name>`），包含以下验证项：

   ```markdown
   # 工作说明书（SOW）质量检查清单：[项目名称]

   **目的**: 在提交双方评审与签署之前验证 SOW 的完整性、合规性与一致性
   **创建日期**: [DATE]
   **文档**: [链接到 SOW 文件]

   ## 合同一致性

   - [ ] 文档名称与合同/项目章程约定一致（尤其是作为付款条件的交付物名称）
   - [ ] 甲方、乙方全称与简称正确且前后一致
   - [ ] 合同编号、签约日期字段已填写或明确标注待定
   - [ ] 页脚文档名称与页码要求已在使用说明中提示（定稿环节遵循）

   ## 范围完整性

   - [ ] 实施业务/模块范围明确
   - [ ] 实施功能范围表已填写（模块/功能/功能描述）
   - [ ] 系统集成范围与双方接口开发职责清晰
   - [ ] 初始数据转换范围与甲乙方数据准备职责明确
   - [ ] 客制化开发与报表范围（含报表数量上限）明确
   - [ ] 系统环境要求（软硬件、网络）职责划分清晰
   - [ ] 范围为“最大实施范围框架”并说明变更走变更流程

   ## 计划与组织

   - [ ] 总体计划阶段、里程碑与交付物已列出
   - [ ] 需求冻结时间与逾期不纳入交付的约定明确
   - [ ] 甲方/乙方责任与义务分别完整
   - [ ] 项目组织架构与通讯录来源说明清楚

   ## 假设、约定与验收

   - [ ] 关键假设条件覆盖资源、组织、数据、采购、办公场所等
   - [ ] 质保服务内容、服务时间与 SLA 指标完整
   - [ ] 问题严重级别（S/A/B/C）定义清晰
   - [ ] 验收标准、验收方法、验收内容与交付物表完整
   - [ ] 附录A 变更控制程序与交付物接受程序完整

   ## 就绪度

   - [ ] 无残留 [NEEDS CLARIFICATION] 标记
   - [ ] 待补充商务/金额字段已在《待补充信息清单》中汇总
   - [ ] 不适用章节已整节删除（无“N/A”残留）

   ## 备注

   - 标记为不完整的项需在提交签署前更新 SOW
   ```

   b. **运行验证检查**: 对照每个检查清单项审查 SOW：
   - 对于每一项，确定其通过或失败
   - 记录发现的具体问题（引用相关章节）

   c. **处理验证结果**:
   - **如果所有项通过**: 将检查清单标记为完成，并继续必选执行后钩子部分

   - **如果有项失败（不包含 [NEEDS CLARIFICATION]）**:
     1. 列出失败的项和具体问题
     2. 更新 SOW 以处理每个问题
     3. 重新运行验证直到所有项通过（最多 3 次迭代）
     4. 如果 3 次迭代后仍然失败，在检查清单备注中记录剩余问题并警告用户

   - **如果 [NEEDS CLARIFICATION] 标记残留**:
     1. 从 SOW 中提取所有 [NEEDS CLARIFICATION: ...] 标记
     2. **限制检查**: 如果超过 3 个标记，仅保留 3 个最关键的问题（按合同主体/范围/付款影响），对其余做出合理推断
     3. 对于每个需要澄清的问题（最多 3 个），以此格式向用户呈现选项：

        ```markdown
        ## 问题 [N]：[主题]

        **上下文**: [引用相关 SOW 章节]

        **需要明确的内容**: [NEEDS CLARIFICATION 标记中的具体问题]

        **建议答案**:

        | 选项   | 答案             | 含义                      |
        | ------ | ---------------- | ------------------------- |
        | A      | [第一个建议答案] | [这对合同/项目意味着什么] |
        | B      | [第二个建议答案] | [这对合同/项目意味着什么] |
        | C      | [第三个建议答案] | [这对合同/项目意味着什么] |
        | 自定义 | 提供你自己的答案 | [说明如何提供自定义输入]  |

        **你的选择**: _[等待用户回复]_
        ```

     4. **关键 - 表格格式**: 确保 markdown 表格格式正确：
        - 使用一致的间距，管道对齐
        - 每个单元格的内容周围应有空格：`| 内容 |` 而非 `|内容|`
        - 标题分隔符必须至少有 3 个破折号：`|--------|`
     5. 按顺序编号问题（Q1、Q2、Q3 - 最多 3 个）
     6. 在等待回复之前一起呈现所有问题
     7. 等待用户对所有问题的选择回复（例如："Q1: A, Q2: 自定义 - [详情], Q3: B"）
     8. 将 SOW 中的每个 [NEEDS CLARIFICATION] 标记替换为用户选择或提供的答案来更新 SOW
     9. 在所有澄清解决后重新运行验证

   d. **更新检查清单**: 在每次验证迭代后，以当前的通过/失败状态更新检查清单文件

## 必选执行后钩子

**必须在向用户报告完成之前完成本节。**

检查项目根目录是否存在 `.adspecs/extensions.yml`。

- 如果不存在，或 `hooks.after_write_sow` 下没有注册钩子，跳到完成报告。
- 如果存在，读取它并查找 `hooks.after_write_sow` 下的条目。
- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续完成报告。
- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/ads-git-commit`。
- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
  - **必选钩子** (`optional: false`) — **必须为每个必选钩子发出 `EXECUTE_COMMAND:`**：

    ```
    ## 扩展钩子

    **自动钩子**: {extension}
    执行: `/{command}`
    EXECUTE_COMMAND: {command}
    ```

  - **可选钩子** (`optional: true`):

    ```
    ## 扩展钩子

    **可选钩子**: {extension}
    命令: `/{command}`
    描述: {description}

    提示: {prompt}
    执行: `/{command}`
    ```

## 完成报告

向用户报告完成情况，包含：

- `SOW_FILE` — SOW 文档路径
- 检查清单结果摘要
- 《待补充信息清单》摘要（需商务/项目经理确认的金额、周期、数量等字段）
- 是否准备好进入双方评审与签署流程

## 快速指南

- SOW 面向**双方项目经理与商务/法务**，用于约束交付边界与责任，而非描述技术实现。
- 明确区分**甲方责任**与**乙方责任**，避免职责空白或重叠。
- 范围描述统一采用“最大实施范围框架”，范围变更一律指向 `附录A-1 项目变更控制程序`。
- 涉及付款条件的交付物名称必须与合同一致；金额、周期、报表数量等敏感字段以占位符保留并汇总待确认。

### 章节要求

- **必填章节**: 前言、项目范围、项目计划、项目组织及职责、关键假设与约定、项目验收、附录A。
- **可选章节**: 术语表、系统集成范围、初始数据转换范围、客制化开发范围、质保 SLA — 仅在与项目相关时保留。
- 当某个章节不适用时，**完全删除**它（不要留下“N/A”）。

### SOW 编写指南

1. **做出合理推断**: 对通用合同条款（问题分级、验收确认时限、集中办公、工作时间、SLA）沿用模板默认值，不逐项询问。
2. **记录假设**: 将默认假设写入“关键假设条件”章节。
3. **限制澄清标记**: 最多 3 个 [NEEDS CLARIFICATION]，仅用于合同主体、范围边界、付款/验收条件等关键决策。
4. **保护已确认信息**: 更新模式下不得用占位符覆盖用户已填写的甲乙方、金额、日期等实际内容。
5. **合规提示**: 在文档中保留定稿、打印、签署、存档的合规要求提示（页脚、骑缝章、签署日期具体到年月日）。

**合理默认值示例**（不要逐项询问）:

- 交付物确认时限：甲方 5 个工作日内未回应视为接受
- 问题严重级别：S/A/B/C 四级及对应 SLA
- 办公模式：实施集中办公（同城），异地由甲方承担差旅
- 工作时间：星期一至星期五 5×8 小时，不含公众假日
- 验收方式：分阶段验收 + 《项目验收报告》整体签署

## SOW 章节结构

当模板文件缺失时，按以下权威结构生成 SOW：

- 封面信息（项目名称、文档名称、合同编号、甲方、乙方、签约日期）
- 文档修改记录（版本 / 日期 / 责任人 / 版本描述）
- 审批签字（甲方项目经理 / 乙方项目经理）+ 保密声明
- 目录
- 1 前言（1.1 文档目的、1.2 相关文档、1.3 术语）
- 2 项目综述（2.1 项目背景、2.2 项目目标）
- 3 项目范围（3.1 项目组织范围、3.2 项目实施地点、3.3 实施范围：3.3.1 业务/模块范围、3.3.2 功能范围、3.3.3 系统集成范围、3.3.4 初始数据转换范围、3.3.5 客制化开发与报表开发范围、3.3.6 系统环境要求）
- 4 项目计划（4.1 总体计划）
- 5 项目组织及职责（5.1 项目组织架构、5.2 责任与义务：5.2.1 甲方责任、5.2.2 乙方责任）
- 6 关键假设与约定（6.1 关键假设条件：6.1.1 一般关键假设、6.2 项目约定：6.2.1 质保服务约定）
- 7 项目验收（7.1 验收标准、7.2 验收方法、7.3 验收内容：7.3.1 验收内容、7.3.2 交付物）
- 8 附录A：项目控制程序（A-1 项目变更控制程序、A-2 交付物接受程序）

## 完成标志

- [ ] SOW 已写入 `SOW_FILE` 并对照质量检查清单验证通过
- [ ] 《待补充信息清单》已汇总需商务/项目经理确认的字段
- [ ] 扩展钩子已根据上述必选执行后钩子规则分发或跳过
- [ ] 完成报告已呈现给用户，包含 SOW 文件路径、检查清单结果与待补充信息摘要