---
name: doc-sync-skill
description: >
  当 PRD 文档版本更新时，自动分析两版 PRD 差异并生成 Change Intent，驱动 DDS 与 AgentSkill 的增量同步更新，最终归档版本矩阵。
  Automatically analyzes PRD version diffs, generates structured Change Intent, drives incremental DDS and AgentSkill updates, and archives version matrix.
  触发场景 Trigger: 当用户提供了新旧两版 PRD 文档并需要同步更新 DDS 和 Skill / 需要执行文档级联变更 / 需要生成版本归档矩阵。
  关键词 Keywords: PRD, DDS, diff, 增量更新, incremental update, change intent, version matrix, skill sync, 文档同步, doc sync, 版本管理。
version: 1.0.0
author: wdd
argument-hint: "--old <old-prd-path> --new <new-prd-path> [--dds <current-dds-path>] [--skills-dir <skills-directory>]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
---

# Doc-Sync-Skill：PRD 增量变更驱动的文档级联同步

本 Skill 用于在软件开发流程中，当 PRD（产品需求文档）从旧版本更新到新版本时，自动完成以下四个阶段的级联同步：

1. **Phase 1 — PRD Diff 分析**：对比新旧 PRD，生成结构化 Change Intent
2. **Phase 2 — DDS 增量更新**：基于 Change Intent 驱动 DDS 只改受影响章节
3. **Phase 3 — AgentSkill 增量更新**：基于 DDS 变更同步更新相关 SKILL.md
4. **Phase 4 — 版本归档**：生成 VERSION_MATRIX.md 追踪所有文档版本关系

> **核心原则**：
> - **最小变更原则** — 只修改受 PRD 变更影响的章节，未提及部分绝对不动
> - **溯源可追踪** — 每一处变更都能追溯到具体的 PRD 变更条目
> - **幂等安全** — 相同输入多次执行应产生相同结果

---

## 前置条件

执行前必须确认以下文件存在：

| 文件 | 必需 | 用途 |
|------|------|------|
| 旧版 PRD（`--old`） | ✅ | PRD diff 基准 |
| 新版 PRD（`--new`） | ✅ | PRD diff 目标 |
| 当前 DDS（`--dds`） | ⚠️ Phase 2 必需 | DDS 增量更新的基础 |
| Skills 目录（`--skills-dir`） | ⚠️ Phase 3 必需 | Skill 增量更新的目标目录 |

### 文件不存在时的降级策略

- **旧版 PRD 不存在**：终止执行，提示用户提供旧版 PRD 路径
- **新版 PRD 不存在**：终止执行，提示用户提供新版 PRD 路径
- **DDS 不存在**：跳过 Phase 2，在 Phase 4 记录"DDS 待创建"
- **Skills 目录不存在**：跳过 Phase 3，在 Phase 4 记录"Skills 待创建"

---

## Phase 1：PRD Diff 分析 → 生成 Change Intent

### 1.1 执行 PRD 差异对比脚本

使用 `scripts/diff_prd.py` 对新旧两版 PRD 进行章节级对比：

```bash
# 运行 PRD 差异对比
python3 "$(dirname "$0")/scripts/diff_prd.py" --old "$OLD_PRD_PATH" --new "$NEW_PRD_PATH"
```

该脚本输出结构化 JSON，包含：
- `added_sections`：新增章节列表
- `modified_sections`：修改章节列表（含 old/new 对比）
- `removed_sections`：删除章节列表
- `summary`：变更摘要

### 1.2 生成 Change Intent 文档

基于脚本输出的 JSON，填充 `references/CHANGE_INTENT_TEMPLATE.md` 模板：

1. 读取模板：`references/CHANGE_INTENT_TEMPLATE.md`
2. 根据 JSON 结果填充所有字段
3. 输出完成的 Change Intent 文档到工作目录

**填充规则**：
- `变更版本`：从新版 PRD 的文档头提取版本号
- `变更日期`：使用当前日期
- `新增需求列表`：对应 `added_sections`
- `修改需求列表`：对应 `modified_sections`
- `废弃需求列表`：对应 `removed_sections`
- `影响模块列表`：从变更章节中提取涉及的模块/组件名称
- `变更摘要`：使用 JSON 中的 `summary` 字段，必要时补充人工判断

### 1.3 Change Intent 质量门禁

生成的 Change Intent 必须通过以下检查：
- [ ] 所有字段非空（或显式标注"无"）
- [ ] 影响模块列表至少 1 项（纯文案修改除外）
- [ ] 变更摘要不超过 500 字
- [ ] 新增/修改/废弃列表与 diff 脚本输出一致

---

## Phase 2：DDS 增量更新

### 2.1 准备 DDS 更新 Prompt

将 Change Intent 和当前 DDS 内容注入 `references/DDS_UPDATE_PROMPT.md`：

1. 读取当前 DDS 全文
2. 读取 Phase 1 生成的 Change Intent
3. 将两者填入 `references/DDS_UPDATE_PROMPT.md` 的对应占位符

**变量替换**：
- `{{CHANGE_INTENT}}` → 完整的 Change Intent 文档内容
- `{{CURRENT_DDS}}` → 当前 DDS 全文

### 2.2 执行 DDS 更新

将准备好的 Prompt 发送给大模型，获得 DDS 增量更新内容。

**输出格式要求**（在 Prompt 中已约束）：
- `[NEW]` 标注新增章节
- `[MODIFIED]` 标注修改章节，含 diff 对比
- `[DEPRECATED]` 标注废弃章节
- 未提及的章节**绝对不修改**

### 2.3 应用 DDS 变更

将大模型返回的增量更新逐章节应用到 DDS 文件：

1. 对 `[NEW]` 章节：插入到 DDS 合适位置
2. 对 `[MODIFIED]` 章节：替换对应章节内容
3. 对 `[DEPRECATED]` 章节：标注废弃标记（保留原文，添加删除线或注释）
4. 更新 DDS 文档头的版本号（按 Prompt 建议）

### 2.4 DDS 变更验证

- [ ] 只有 Change Intent 中涉及的章节被修改
- [ ] 未涉及章节内容与原文完全一致
- [ ] 文档版本号已更新
- [ ] 无语法错误（Markdown lint 通过）

---

## Phase 3：AgentSkill 增量更新

### 3.1 一致性检查

运行 `scripts/sync_check.py` 检查 DDS 与 Skills 的对应关系：

```bash
python3 "$(dirname "$0")/scripts/sync_check.py" --dds "$DDS_PATH" --skills-dir "$SKILLS_DIR"
```

该脚本输出不一致报告：
- DDS 中有定义但无对应 Skill 的模块
- Skills 目录中有 Skill 但无对应 DDS 章节的模块

### 3.2 确定需要更新的 Skill 列表

基于 Phase 2 的 DDS 变更内容，确定受影响的 Skill 列表：

1. 提取 DDS 中 `[NEW]`/`[MODIFIED]`/`[DEPRECATED]` 章节涉及的模块名
2. 在 Skills 目录中查找对应的 SKILL.md 文件
3. 对于 DDS 新增模块但无 Skill 的情况，标记为"需新建 Skill"

### 3.3 执行 Skill 增量更新

对每个受影响的 Skill，使用 `references/SKILL_UPDATE_PROMPT.md` 驱动更新：

**变量替换**：
- `{{DDS_DIFF}}` → 该模块涉及的 DDS 变更内容（`[NEW]`/`[MODIFIED]`/`[DEPRECATED]` 片段）
- `{{SKILL_NAME}}` → 当前 Skill 的 name 值
- `{{CURRENT_SKILL_MD}}` → 当前 SKILL.md 全文

**更新规则**：
- 只更新受 DDS 变更影响的部分
- version 字段 patch 版本 +1
- 输出完整的新 SKILL.md 内容（直接覆盖写入）

### 3.4 Skill 更新验证

对每个更新后的 Skill 执行以下检查：
- [ ] SKILL.md 的 YAML frontmatter 格式正确
- [ ] version 字段已递增
- [ ] name 字段未被修改
- [ ] description 保持单行且 < 1024 字符
- [ ] 未受影响的章节内容未被修改

---

## Phase 4：版本归档

### 4.1 生成 VERSION_MATRIX.md

基于 `assets/VERSION_MATRIX_TEMPLATE.md` 模板，追加一行新的版本记录：

| 字段 | 取值来源 |
|------|---------|
| 迭代日期 | 当前执行日期 |
| PRD版本 | 新版 PRD 中提取的版本号 |
| DDS版本 | 更新后 DDS 的版本号 |
| 受影响Skill | Phase 3 中更新的 Skill 名称列表 |
| 变更摘要 | Change Intent 中的变更摘要 |
| Git Commit | 预留占位（手动填写或自动获取） |

### 4.2 归档文件存放位置

VERSION_MATRIX.md 存放在项目根目录或用户指定目录，采用**追加模式**：
- 如果文件已存在，在表格末尾追加新行
- 如果文件不存在，从模板创建并填入第一条记录

---

## 异常处理规则

| 异常场景 | 处理策略 |
|---------|---------|
| 旧版/新版 PRD 文件不存在 | 终止执行，输出错误信息 |
| diff_prd.py 脚本执行失败 | 输出错误日志，提示用户手动对比 |
| DDS 文件不存在 | 跳过 Phase 2/3，仅执行 Phase 1/4 |
| Skills 目录不存在 | 跳过 Phase 3，仅执行 Phase 1/2/4 |
| DDS 更新 Prompt 返回格式异常 | 要求重新生成，最多重试 2 次 |
| Skill 更新后 frontmatter 格式错误 | 回滚该 Skill 更新，标记为需人工修复 |
| sync_check.py 发现不一致模块 | 在 VERSION_MATRIX 中记录，不阻断流程 |

---

## 输出清单

每次执行完成后，必须输出以下产物清单：

```
📋 Doc-Sync 执行报告
├── [Phase 1] CHANGE_INTENT.md        — PRD 变更意图文档
├── [Phase 2] DDS 更新文件            — 增量更新后的 DDS（如适用）
├── [Phase 3] 更新的 SKILL.md 列表    — 增量更新后的 Skills（如适用）
├── [Phase 4] VERSION_MATRIX.md       — 追加后的版本矩阵
└── [报告]    执行摘要                 — 各 Phase 执行状态汇总
```

---

## Quick Reference

| 需要了解... | 查阅... |
|------------|--------|
| Change Intent 的结构模板 | `references/CHANGE_INTENT_TEMPLATE.md` |
| DDS 增量更新 Prompt | `references/DDS_UPDATE_PROMPT.md` |
| Skill 增量更新 Prompt | `references/SKILL_UPDATE_PROMPT.md` |
| PRD 差异对比脚本 | `scripts/diff_prd.py` |
| DDS-Skill 一致性检查脚本 | `scripts/sync_check.py` |
| 版本矩阵归档模板 | `assets/VERSION_MATRIX_TEMPLATE.md` |