spec-archive

name	spec-archive
description	在一个 change 已完成实现、修正和审查后，负责做归档收尾与知识沉淀。用于用户要求 archive、归档需求目录、从 `log.md` 提炼知识发现与踩坑记录、逐条确认是否沉淀到 `docs/knowledge/`，并将已完成的 change 目录移入 `docs/archives/` 时使用。

spec-archive

协同技能

在执行本 skill 时，同时遵守 ../../references/full-sdd-lifecycle.md 中 spec-archive 阶段的协同规则。

• 用本插件 skills/documentation-and-adrs/SKILL.md 判断什么该沉淀为长期知识
• 用本插件 skills/shipping-and-launch/SKILL.md 的收尾心智确认当前 change 已真正闭环
• 本 skill 负责把活跃变更移出工作区，不负责替代审查或修正阶段

目标

完成需求闭环后的最后一步：先提炼和确认长期有效知识，再归档 change 目录。

• 从 log.md 中识别值得长期保留的知识发现和踩坑记录
• 逐条向用户展示，并询问是否沉淀到 docs/knowledge/
• 对已确认沉淀的内容立即执行落盘
• 将完成态的 change 目录移入 docs/archives/

进入条件

执行前先确认以下条件成立：

• 对应 change 目录存在，且至少包含 log.md
• 最好同时存在 spec.md、tasks.md，以便判断该 change 是否已闭环
• 当前 change 已完成主要实现与修正，不再处于活跃开发中
• 用户明确要求归档、沉淀知识、清理活跃 change，或结束当前需求闭环

若以下任一情况成立，先停止，不归档：

• log.md 缺失，无法提炼知识发现
• 当前 change 仍处于 apply、fix 或 review 中
• 归档目录或知识目录不存在且无法安全补齐
• 用户尚未确认哪些发现需要沉淀到 docs/knowledge/

执行顺序

按以下顺序执行，不要跳步。

1. 锁定归档输入

先读取最小必要上下文：

• 读取 change 目录中的 log.md
• 按需补读 spec.md、tasks.md，确认该 change 的完成状态与范围
• 读取 docs/knowledge/README.md，确认知识沉淀的位置和索引方式
• 确认归档目标目录为 docs/archives/

执行时坚持下面约束：

• 只从文档和代码事实中提炼知识，不凭印象总结
• 不把一次性的临时操作误写成长期知识
• 不跳过用户确认，直接把所有发现批量塞进 docs/knowledge/

2. 逐条提炼知识与踩坑

从 log.md 中拆出候选条目，至少区分两类：

• 长期知识：稳定的背景、术语、实现约束、依赖习惯、结构约定
• 踩坑记录：高概率复现的问题、误区、限制、修复手法和规避方式

提炼时要做筛选：

• 能长期复用的，才进入候选
• 仅对本次 change 有效、没有复用价值的，不进入知识库
• 描述要压缩成可索引、可复用、可被后续实现直接利用的表述

3. 逐条向用户确认

在落盘前，必须逐条展示候选内容并征求确认。

• 每条都说明来源、建议落点和建议写法
• 明确询问是否沉淀到 docs/knowledge/
• 对用户确认的条目立即执行
• 对用户拒绝的条目，不写入知识库

不要把“展示候选”和“已经写入”混为一谈。

4. 沉淀到知识库

对已确认的条目，立即同步到 docs/knowledge/。

• 优先更新 docs/knowledge/README.md 中合适的小节或索引
• 若信息量明显超出 README 承载范围，再新增知识文档，并在 README 中补索引
• 写入时只保留事实、背景、长期约束和踩坑，不写执行命令式指令
• 若某条内容本质上属于工程规则、质量门禁或长期约束，优先建议沉淀到 docs/rules/

若沉淀内容已经触达长期规则边界，应停止并建议改写到 docs/rules/，不要误放到 docs/knowledge/。

5. 归档 change 目录

在知识沉淀完成后，再执行目录归档。

• 确认目标路径为 docs/archives/
• 将当前已完成的 change 目录整体移入 docs/archives/
• 归档后保证活跃目录中不再保留该 change 的重复副本

若移动目录会覆盖已有归档、破坏现有结构或导致引用失效，先停止并汇报。

6. 汇报归档结果

向用户汇报时至少包含：

• 从 log.md 提炼出了哪些候选条目
• 哪些条目已确认并沉淀到 docs/knowledge/
• 哪些条目被明确放弃或暂缓
• change 目录是否已归档到 docs/archives/

紧急停车

遇到以下情况时立即停止：

• 无法判断当前 change 是否已完成
• 候选知识与规则边界混淆，无法确定应写入 knowledge 还是 rules
• 归档动作会覆盖既有归档目录
• 用户尚未确认沉淀项，但已准备执行写入或移动

停止时要说明：

• 当前阻塞点
• 受影响的归档动作
• 建议先补哪份文档或先完成哪个阶段

硬门控

• 必须逐条展示 log.md 中的知识发现和踩坑记录
• 必须先征求用户确认，再写入 docs/knowledge/
• 沉淀知识完成后，才允许归档目录
• 归档目标目录固定为 docs/archives/
• 不把长期规则误写到 docs/knowledge/
• 若当前 change 尚未通过 review 或仍有开放 fix，不允许提前归档

质量检查

交付前自行检查：

• 候选条目是否都来自 log.md 的真实记录
• 已沉淀内容是否适合放入 docs/knowledge/
• README 索引是否同步
• change 目录是否已安全移动到 docs/archives/
• 是否清楚告知用户哪些内容已沉淀、哪些没有

最后处理

• 在docs/changes/templates/README.md中修改内容，说明已归档并修改新的文件链接
• 在归档后，需要进行git commit，具体的规范各查看docs/rules/git.md。若没有规范，则按照常规的git commit message规范进行提交，提交信息需要包含归档的change目录名称和归档的内容概述，例如：feat: xxx需求已完成。注意，提交后等待用户审查后再执行push操作！