ddev-archive

name	ddev-archive
description	实现 + 调试全部完成后，扫描活跃计划、聚合同主题的多轮迭代计划、归档并生成最终代码事实设计文档

ddev-archive — 变更归档与最终设计定型

把同一主题下经过多轮迭代（初始计划、调试迭代、最终版本）的所有活跃计划归档到一个日期目录，并生成一份 final-spec.md 记录最终代码事实设计。

开始时声明： "正在使用 ddev-archive skill 归档变更。"

何时使用

• 实现 + 所有调试迭代已完成，代码已提交
• 同一功能经历了多轮 plan（初始 spec → 调试后调整 → 再次调试 → 最终版本）
• 最终设计与原始 spec 存在差异（调试中修改了方案）
• 准备关闭 feature 分支、清理工作区或进入发布前
• 需要给后续维护者留下"实际长什么样"的最终设计文档

不使用的情况：

• 还没开始实现 → 先用 ddev-spec
• 还在调试中 → 先调完再说
• 实现与原计划完全一致且只有一个 plan → 可以归档，但 final-spec.md 只需简述"实现与初始 plan 一致，无偏离"

归档目录结构

docs/plans/archive/YYYY-MM-DD/
├── 01_initial/              ← 初始计划（最早的 spec/detail/exec_plans）
│   ├── spec/
│   ├── detail/
│   └── exec_plans/
├── 02_iter1/                ← 调试后迭代 1（如有）
│   ├── spec/
│   ├── detail/
│   └── exec_plans/
├── 03_iter2/                ← 调试后迭代 2（如有）
│   └── ...
├── 04_final/                ← 最终版本（如有独立 plan）
│   └── ...
├── final-spec.md            ← 综合所有迭代的最终代码事实设计
└── archive-notes.md         ← 归档说明（可选，记录归档决策和未决项）

• YYYY-MM-DD 为归档日期（当天）
• 数字前缀 01_ / 02_ 保持时间顺序
• 如果只有一个 plan 无迭代，则只有 01_initial/ + final-spec.md

流程

第一步：扫描活跃计划

1. 确定本次变更的主题名/功能名。从当前 spec 文档标题、用户指定或对话上下文提取。
2. 扫描 docs/plans/ 目录（排除 archive/ 子目录），列出所有与本次主题相关的计划目录。
3. 相关性判断：
   • 目录名包含相同主题关键词（如 usb-hid、usb_hid、hid-report）
   • 目录下的 spec 文档标题或内容引用同一功能
   • 用户显式指定了哪些目录属于同一变更
4. 如果扫描结果超过 5 个目录，列出清单让用户确认哪些属于本次变更。

第二步：排序与分类

按日期和时间顺序排列所有相关计划目录：

1. 最早的计划 → 标记为 01_initial（初始计划）
2. 中间的调整计划 → 按时间顺序标记为 02_iter1、03_iter2...
3. 最后的计划 → 标记为 0N_final（最终版本）

如果只有一个计划目录，直接标记为 01_initial。

分类规则：

• 从目录名中的日期提取时间顺序
• 如果目录名无日期，按文件修改时间排序
• 不确定时列出排序结果让用户确认

第三步：读取所有迭代的设计文档

对每个迭代目录，读取以下关键文件：

1. spec 文档：Delta Summary 表、模块边界图、联动修改清单
2. detail 文档：结构体定义、数据流、流程图
3. exec_plans：实现计划中的任务列表和验证结果
4. implementation-notes.md：Design Decisions、Deviations、Tradeoffs
5. progress.md：执行日志和验证结果

第四步：生成 final-spec.md

基于所有迭代文档的对比分析，生成最终代码事实设计文档。

文档位置

docs/plans/archive/YYYY-MM-DD/final-spec.md

文档结构

# [功能名] — 最终代码事实设计

> **归档日期**: YYYY-MM-DD | **迭代次数**: N | **最终版本**: 0N_final
>
> 本文档综合 [N] 轮迭代的设计文档，记录经过实机调试后的最终代码事实。
> 如与某轮迭代的设计存在差异，以本文档为准。

## 1. 变更面总览 (Delta Summary)

| 类型 | 对象 | 最终状态 |
|------|------|---------|
| ADDED | ... | ... |
| MODIFIED | ... | ... |
| REMOVED | ... | ... |

> 此表综合所有迭代的最终结果。与初始计划的差异在 §2 中说明。

## 2. 与原计划的关键差异

| 迭代 | 原计划 | 最终实现 | 原因 |
|------|--------|---------|------|
| 01_initial | [初始设计要点] | [实际落地情况] | [调试发现/框架约束/...] |
| 02_iter1 | [迭代1调整] | [实际落地情况] | ... |

> 如果只有一轮且无差异，写"实现与初始 plan 一致，无偏离"。

## 3. 最终架构总览

(ASCII 图 — ddev-diagram 规范 — 反映最终代码的模块边界和调用关系)

## 4. 最终核心数据结构

(经过调试确认的最终结构体、枚举、状态机定义)

每个结构体/枚举必须标注：
- 来源：来自 `01_initial/detail/structures/xxx.md`，在 `02_iter1` 中修改了字段 Y
- 如果与任何一轮设计文档不同，标注差异

## 5. 最终核心流程

(ASCII 图 — 反映最终代码的实际数据流和关键流程)

## 6. 调试发现的问题及修复

### Bug 1: [标题]

| 项目 | 内容 |
|------|------|
| 发现于 | 0N_iterX |
| 症状 | ... |
| 根因 | ... |
| 修复 | ... |
| 影响的设计文档 | 0N_iterX 的 spec/detail 中 xxx 部分 |

## 7. 未覆盖风险与已知限制

- [风险/限制 1]：[说明及缓解措施]
- [风险/限制 2]：[说明及缓解措施]

## 8. 设计决策记录

| 决策 | 触发迭代 | 决策内容 | 替代方案（为什么没选） |
|------|---------|---------|---------------------|
| ... | 02_iter1 | ... | ... |

⚠️ 硬门禁：画图前必须先加载 ddev-diagram

在任何 ASCII 图动笔之前，必须执行 Skill("ddev-diagram") 加载绘制规范。

第五步：创建归档目录并移动文件

1. 创建 docs/plans/archive/YYYY-MM-DD/
2. 将每个迭代目录复制/移动到对应的 0N_xxx/ 子目录
3. 将 final-spec.md 写入归档根目录
4. 删除原 docs/plans/ 下的活跃计划目录（移动后清理）

第六步：生成 archive-notes.md（可选）

如果存在以下情况，创建 archive-notes.md：

# 归档说明

> 归档日期：YYYY-MM-DD

## 归档范围
- 0N_iterX：简述
- ...

## 未归档内容
- [如果有相关但未纳入归档的文件，说明原因]

## 未决项
- [Open Questions 中仍未解决的问题]

图怎么选

优先画：

1. 最终架构总览（模块框 + 调用关系，反映最终代码）
2. 最终核心流程（数据流/时序图）
3. 关键数据结构对比（如有迭代间结构变化）

不需要画：

• 各迭代中已正确且未变化的部分（引原文档即可）
• 调试过程中被废弃的方案

写法原则

• 只写最终状态：不写"调试过程中试过 A 不行换 B 最后选了 C"
• 差异必须标注：如果最终实现与某轮设计文档不同，必须显式标注
• 图优先：能用图说清的不用长文
• 引不抄：原 spec 里正确且不变的部分，一句话引原文档，不重复写
• 代码事实为准：final-spec 描述的是代码实际行为，不是"应该是这样"

与其他 skill 的关系

• 上游：ddev-exec（实现）+ 实机调试（可能产生多轮迭代 plan）
• 并行：ddev-diagram（画图规范）
• 下游：neat-freak（归档清理时引用 final-spec.md）
• 替代关系：原各迭代的 spec 文档保留在归档目录中作为设计意图记录，final-spec.md 为最终权威版本

自检

归档完成后逐项核对：

1. 迭代完整性：是否找到了所有相关计划目录？遗漏的目录是否已确认不属于本次变更？
2. Delta Summary：final-spec.md 的 Delta Summary 是否覆盖了所有迭代的最终变更面？
3. 差异覆盖：是否每轮迭代的"原计划 vs 最终实现"差异都已记录？
4. 最终架构图：是否反映实际代码的模块边界和调用关系（而非某轮设计文档的复制）？
5. 数据结构一致性：final-spec.md 中的结构体/枚举是否与 .h 中的实际定义一致？
6. ASCII 图规范：所有 ASCII 图是否通过 ddev-diagram 门禁？
7. 目录清理：原 docs/plans/ 下的活跃计划目录是否已移除？
8. Debug bug 完整：每个调试发现的 bug 是否有症状/根因/修复三要素？