---
name: docs-retro
description: >-
  从对话、文档变更及审计记录中复盘文档管理的问题和经验，减少资料难找、同步遗漏、重复维护和旧说明误用。用户要求“复盘文档管理”“为什么文档总漏更新”“总结文档治理经验”，或项目约定文档管理阶段复盘时使用；默认只读，输出有证据、适用条件和落点的改进建议。
---

# 文档管理复盘

追查文档问题为什么发生、为什么重复，提炼有效的管理办法。用户要求或项目约定时执行；同类问题反复出现时可建议复盘，不默认每轮总结。维护负责同步当前内容，审计负责发现问题，本 Skill 改进产生这些结果的管理方式。

## 1. 找到相关记录

明确复盘的文档问题或阶段；未指定时只看当前任务中的文档管理过程。按问题、文档或关键词检索对话、文档变更、审计发现和项目历史记录，再沿链接读取相关 PR、Issue 与验证证据，不全量加载历史。

说明实际读取范围与缺失材料。业务故障、代码设计和领域经验只有在解释文档管理问题时才作为背景，不扩展为通用项目复盘。

## 2. 找值得留下的经验

沿以下六个方向找候选，不要求每次凑齐：

| 方向 | 从记录中追问 | 值得留下什么 |
|---|---|---|
| 文档写法 | 用户为什么反复纠正说明？是否含糊、冗长或缺少适用条件？ | 已确认有效的写法与适用范围 |
| 查找与导航 | 为什么反复搜索、找错文档？分类、命名或入口哪里失效？ | 归类与导航改进 |
| 同步遗漏 | 为什么改了功能却漏更新资料？触发、影响检索还是交接漏了？ | 同步时机、范围及交接改进 |
| 主源与历史 | 为什么多份说明冲突、旧方案被当成现状？ | 主源、引用及状态区分办法 |
| 审计遗漏 | 为什么已有检查没发现问题？是覆盖不足、未执行还是判定不准？ | 检查范围、方法或执行入口改进 |
| 有效做法 | 哪种写法、组织或检查实际减少了查找、遗漏和返工？ | 有证据的可复用做法与使用条件 |

## 3. 判断是否可复用

对照原始记录、已确认的文档约定和现有措施，区分已证实的问题、原因假设与有效经验。已有机制先查是否未接入或失效，不因一次失误就新增永久规则或重复检查。

只保留能改善下次文档管理的经验，合并重复；证据不足列待验证建议，没有新发现就不新增内容。曾经有效的办法也要核对当前条件，保留历史依据。

## 4. 给出具体改法

按影响排序，结合证据与适用条件，定位项目现有文档或管理流程的具体文件、章节或步骤，说明增加、修改或删除什么，给出简短修改草稿和下次验证办法。已有规则足够时，指出未执行的环节，不重复加规则。沿用已有主记录：

- 写作与归类改进 → 现有写作约定或主题入口；常驻入口按 `agent-entrypoints` 取舍。
- 导航与资料定位经验 → `CLAUDE_MAP.md`，更新“什么时候读、去哪里找”的指针，正文留在对应文档。
- 同步与审计改进 → 现有维护流程、审计规则或检查入口；指出具体位置和何时执行，不另造一套流程。
- 重要改进事件 → 项目约定的历史主源；已有 LOG 按约定追加索引，否则复用 PR／Issue／决策或能承载原因、依据和版本的 Git 记录，不另建流水，保留原有历史。经验正文只维护一处。

例如：确认漏更接入指南是缺少导航后，在 `CLAUDE_MAP.md` 的接口入口补“修改接口时，读取〈项目实际接入指南路径〉并核对调用示例”。草稿中的路径须替换为已找到的文件；下次接口变更时验证能否找到并同步该指南。

默认在回复交付建议；获准后落实到对应位置，新增检查或外部任务须在授权范围内。完成时说明范围与缺口，区分建议、已落实和已验证；写入文档不等于效果已验证，不默认另建报告、MEMORY 或 Skill。