/docs-maintenance

name: docs-maintenance
description: >-
  每轮任务结束时同步本次变化涉及的文档。由项目收尾约定或用户要求“同步文档”“收尾”“准备交接”时调用；也用于处理已发现的文档与项目事实冲突。

日常文档维护

让下一位使用者或开发者读到的说明与本次变化一致。只维护受影响的文档；只读任务只报告差异。

需要每轮自动接入时，由 `agent-entrypoints` 在项目共享入口配置以下约定，Skill 名替换为实际可读取路径，外部插件使用完整路径：

> 每轮完整任务结束、最终回复前，执行 docs-maintenance；没有相关变化就不改，只读任务只报告差异。

“一轮”指完整任务，维护本身不递归触发。入口约定由 Agent 执行，Skill 文件本身不会自动运行，也不自行安装 Hook。

1. 确定这次改变了什么

结合本轮对话、实际 diff 和确认材料，说清**什么行为变了、影响谁、依据是什么**，不只列改过的文件。例如“订单取消时限从 30 分钟改为 60 分钟”，会影响用户说明与验收条件。由模块变更流程进入时，复用任务基线、影响清单和回归结果。

区分已确认需求、实际实现、上线状态与验证结果；测试失败或未运行不能写成已验收。没有相关变化就说明无需同步；缺少 Git 基线时依据现有材料核对，标出无法确定的旧状态。

2. 找到受影响的说明，就地更新

先复用本轮有效影响分析：范围、版本及未提交变化一致，且包含该范围要求的审计结果；出现新变化、失败或未覆盖项时，不沿用旧结论，按 `skills/engineering/change-impact/SKILL.md` 的“按事实核对文档”补查。它提供候选与依据，本 Skill 判断并修改正文。沿项目入口补查相关说明；零命中不等于无影响。

对每处说明判断：**下一位读者照着做，是否还会得到文档承诺的结果？** 根据变化定位现有主记录：

| 本次变化 | 重点核对 | |---|---| | 功能、使用方式或操作命令 | README、使用说明及操作文档中的步骤和预期结果 | | 接口、配置或数据结构 | 契约、接入说明和调用示例；旧用法是仍受支持，还是已失效？契约写法沿用 `contract-first` | | 文件位置或模块关系 | MAP 和相关引用；架构变化交给 `architecture-docs` | | 需求、决策或稳定约定 | PRD／Spec、ADR 或项目入口；分别按 `product-evolution`、`domain-modeling`、`agent-entrypoints` 处理 | | 进展、风险或验证结果 | STATUS 对应条目；旧证据是否仍适用于当前版本？任务排期仍留 Tracker | | 值得追溯的重要事件 | 沿用项目约定的历史主源，保留原因、确认依据和相关版本；已有 LOG 按约定追加，否则复用 PR／Issue／决策或能承载这些信息的 Git 记录，不另建流水，保留既有历史 |

沿用项目实际路径，不为凑齐表格创建文件。在获准范围内修改过时条目、失效引用和重复的现役正文，同一事实只维护一处，其余引用；保留条件、例外和必要案例。

例如，接口字段改名后，更新当前接入指南和调用示例；历史日志中的旧字段名可以保留。实现与已确认需求冲突时分别记录依据，不能直接把需求改成代码现状；主源不明或无法裁决时列出待确认项。

3. 验证更新，并交代剩余差异

先检查受影响的路径、引用与正文，再运行项目已有相关检查；示例或其依赖变化时按下节验证。旧结论依赖的行为或条件变化后须复验，未运行标待复验。

示例与命令怎么验证

本轮修改了示例，或改变了它依赖的接口、参数、配置、环境时，再验证相关示例与命令：

• 从文档原文取示例，确认适用版本、工作目录、依赖和预期结果，复用现有测试或契约检查；说明占位符替换，不只验证手写副本。
• 可安全执行的内容在隔离环境运行，同时检查退出码和实际输出。片段缺少前置条件时说明检查限制；发布、删除、付费或使用凭据仍须在已有授权范围内，不全量执行文档代码块。
• 失败时区分过期示例、实现错误和环境缺失，按已确认需求修复本轮问题后复跑，保留原验收要求。历史示例保留当时语义，不当作当前指南执行。

接口样例的失败、修复与复验见[可复跑案例](../../engineering/change-impact/examples/interface-change.md#示例与命令验证)。

完成时在回复或已有测试记录中简述：已同步内容（或无需同步的理由）、待确认差异、失败及未验证范围；附受检版本、文档位置和实际命令／环境、预期与结果。本次受影响的主记录和查到的引用均应已处理；未解决项写清位置、依据和下一步，并标为部分完成。无需另建报告或台账，脚本通过不代表内容全部一致。