ce-compound-refresh

随着时间的推移维护 docs/solutions/ — 根据当前代码库回顾现有知识，然后更新、合并、替换或删除漂移的知识。

ce-compound-refresh 是机构知识的维护技能。随着代码的发展，学习内容发生变化：文件路径发生变化，类被重命名，建议的修复成为反模式，两个文档从稍微不同的角度涵盖了相同的问题。如果没有定期维护，docs/solutions/ 就会变成一堆半真半假的指导，其误导性多于其帮助。这项技能是定期审查，以保持精简和值得信赖。

它与 ce-compound 配对：该技能捕获新知识；该技能维护现有的集合。它们一起形成了一个反馈循环——每个解决的问题都会成为一个文档，随着代码库的发展，每次刷新都会使这些文档保持诚实。

TL;DR

＃＃ 问题

docs/solutions/ 以可预测的方式累积漂移：

• 重命名和移动 — 学习参考 app/models/auth_token.rb，但文件现在是 app/models/session_token.rb
• 架构转变 - 推荐的修复现在是一种反模式；新架构以不同的方式处理问题
• 无声重复 - 两篇文章从不同角度描述了同一问题，相隔数月写成，但他们开始出现分歧
• 没有支持学习的模式文档 - 一个普遍规则，其基础证据已经发生了变化
• 死文档不会死 - 三季度前删除的代码，但学习仍然存在
• 不断增长的存档文件夹 — _archived/ 目录会污染搜索结果并且无人读取

如果没有积极的维护，知识存储就会失去可信度。未来的智能体（和人类）会查阅部分错误的文档，采纳不再适用的建议，复合效应会逆转：糟糕的学习会让工作变得“更难”，而不是更容易。

解决方案

ce-compound-refresh 作为结构化审查运行，有五个明确的结果：

• 保留 — 准确且有用；没有编辑
• 更新 — 参考文献发生了漂移，但解决方案仍然是正确的；应用就地修复
• 合并 — 两个文档严重重叠；将唯一内容合并到规范文档中，删除包含的内容
• 替换 — 旧的指导现在具有误导性；编写一个后继（通过子代理进行上下文隔离）并删除旧的
• 删除 — 代码消失了，问题域消失了，没有传入的实质性引用；删除文件（git历史记录是存档）

该技能首先进行调查（第 1 阶段根据当前代码库读取每个文档），然后执行文档集分析（第 1.75 阶段捕获仅在文档中可见的问题），然后进行分类，然后执行 - 通过 PR 或直接将更改提交到当前分支。

是什么让它如此新颖

1. 五个维护成果——明确的决策，而不是模糊的“审计”

大多数“查看文档”提示都会崩溃为“这仍然是正确的吗？” → 模糊的答案。五结果模型强制每个文档做出特定决策和特定操作：保留不执行任何操作，更新应用就地修复，合并合并和删除，替换写入后继，删除删除文件。每个都有自己的证据栏。

2. 两种模式 — 交互式默认模式、mode:autofix 上的自动修复

交互式（默认）针对不明确的情况一次提出一个问题，并提出建议。 Autofix 无需用户交互即可处理所有文档，应用所有明确的操作，并将不明确的情况标记为过时（在 frontmatter 中使用 status: stale、stale_reason、stale_date）以供后续人工审核。自动修复报告有两个部分：已应用（成功写入）和推荐（无法应用的写入 - 例如，权限被拒绝 - 具有完整的理由，以便人们可以应用它们）。

3. 文档集分析 — 捕获每个文档审核所遗漏的内容

阶段 1.75 评估整个文档集：跨五个维度的重叠检测（问题陈述、解决方案形状、引用文件、预防规则、根本原因）、取代信号（较新的规范文档包含较旧的窄前体）、每个主题簇的规范文档识别以及跨文档冲突检查。涉及相同领域的两篇文档最终会分道扬镳并相互矛盾——这比一篇稍长的单个文档更糟糕。

4. 通过子代理替换——上下文隔离

当学习的核心指导现在具有误导性时，编排器会分派一个子代理来编写替换内容（一次一个，按顺序 - 替换内容可能需要阅读重要的代码，而并行性可能会导致上下文耗尽）。子代理接收旧的学习、调查证据、目标路径和契约文件（架构、类别映射、模板），并编写一个干净的后继程序，而不会污染编排器的上下文。

5. 证据不足时标记陈旧

当偏差如此根本以至于代理无法自信地记录当前方法（整个子系统被替换，新架构太复杂而无法从文件扫描中理解）时，该文档会被标记为 status: stale ，而不是错误地替换。建议：在下次遇到该区域后，当存在新的问题解决上下文时，运行 /ce-compound 。

6.自动删除安全性——三个条件

仅当所有三个都为真时才会触发自动删除：

• 实施已经消失（或完全被明显更好的继任者取代，或者文档显然是多余的）
• 问题域消失了——应用程序不再处理学习内容
• 缺少入站链接或没有明确的装饰性链接

如果任何条件失败（包括其他文档的实质性引用），则该技能将被分类为替换、更新、合并或陈旧标记。 自动删除+装饰引文清理就可以了；实质性引用或真正的歧义将降级为过时标记。

7. 入站链接分类 — 装饰性与实质性

在删除文档之前，该技能会在存储库的降价中搜索文件的引用。每个引用被分类：

• 装饰性 - 内联陈述的原则，引用是“另请参阅”指针。删除+清理是机械的。
• 实质性 - 引用文档依赖于引用文档中未内嵌说明的内容。信号替换；不要删除。
• 混合/不清楚 — 陈旧标记。

入站链接通知分类，而不仅仅是清理——引用重写了操作选择，而不仅仅是删除后的修复。

8. 将文档与现实相匹配，而不是相反

当当前代码与学习不同时，技能会更新学习以反映当前代码。 它不会询问用户代码更改是“有意的”还是“回归” - 这是一个代码审查问题，而不是文档维护问题。该技能的作用是文档准确性。如果用户认为代码是错误的，那么这是该工作流程之外的一个单独的问题。

9.删除，不存档

已删除的文档将被删除，而不是移动到 _archived/。 Git 历史记录会保留每个已删除的文件 (git log --diff-filter=D -- docs/solutions/)。专用的存档目录会累积并污染搜索结果。如果在此约定之前存在 _archived/ 目录，则技能会将其标记为在报告中进行清理。

10.可发现性检查继续进行

与 ce-compound 一样，每次刷新运行都会检查 AGENTS.md/CLAUDE.md 是否表面 docs/solutions/。每次都会进行检查——只有当客服人员能够找到知识时，知识才具有复合价值。在自动修复模式下，建议显示在报告中而不是被应用（自动修复范围是文档维护，而不是项目配置）。

简单示例

您刚刚合并了一个重构，该重构在 auth 子系统中重命名了多个模型。您调用 /ce-compound-refresh auth。

该技能发现 5 个学习内容和 2 个与 auth 匹配的模式文档（通过目录、frontmatter、文件名或内容搜索）。第 0 阶段路由作为重点范围。

第一阶段调查每个文档。三个不再存在的参考文件（auth_token.rb → session_token.rb）。一个已被较新的文档完全取代。有一个还是准确的。一个模式文档概括了最近的架构更改所打破的规则。

阶段 1.75 表面重叠：两个学习内容从略有不同的角度涵盖了相同的身份验证错误处理问题。较新的内容更广泛、更准确。

第 2 阶段分类：3 项更新（重命名引用）、1 项合并（将旧的验证错误文档合并到新的文档中并删除旧的）、1 项保留、1 项替换（模式文档 — 旧的概括不再成立）。替换的内容被分派给子代理，该子代理读取合同文件并写入后继文件；协调器删除旧的。

第 3 阶段（交互模式）与您确认合并选择（规范文档选择并不总是显而易见）。其他操作直接应用。第 5 阶段作为当前功能分支上的单独提交进行提交，并带有描述性消息。

该报告列出了每个文档、做了什么以及为什么。

何时去实现它

在以下情况下使用 ce-compound-refresh：

• 重大重构或重命名刚刚落地，该领域的学习内容可能会发生变化
• ce-compound 将特定的旧文档标记为被新学习所取代
• 您注意到所学知识在没有定期回顾的情况下不断积累
• docs/solutions/ 中的两个文档看起来涵盖了相同的问题
• 您需要定期进行卫生清扫（例如每季度一次）以保持知识库的精简

在以下情况下跳过 ce-compound-refresh：

• 你实际上并没有注意到任何漂移——没有证据的大范围扫描会产生流失
• 文档是最新的，代码库区域尚未移动
• 您正处于调试或构建会话中 — 首先通过 /ce-compound 捕获，稍后刷新

用作工作流程的一部分

ce-compound-refresh 是 /ce-compound 的维护对应项：

• 从 /ce-compound 触发 — 当新的学习表明旧文档可能已过时时，阶段 2.5 的选择性刷新检查会通过窄范围提示
• 手动定期调用 - 通常限定范围（/ce-compound-refresh auth、/ce-compound-refresh performance-issues），以避免在没有证据的情况下进行全面审查
• 发布前卫生 — 在主要发布之前扫描 docs/solutions/，以确保记录的学习内容反映运输现实

配对很重要：ce-compound 添加了新文档； ce-compound-refresh 确保现有集合保持精简。没有第二个，第一个最终会变得混乱。

使用独立版

该技能是通过范围提示直接调用的，从而缩小了审查范围：

• 特定文件 — /ce-compound-refresh plugin-versioning-requirements
• 模块/组件 — /ce-compound-refresh payments
• 类别 — /ce-compound-refresh performance-issues
• 模式主题 — /ce-compound-refresh critical-patterns
• 自动修复模式 — /ce-compound-refresh auth mode:autofix（无用户交互；报告是可交付成果）
• 广泛扫描（罕见）- /ce-compound-refresh 无范围，处理所有内容

如果没有范围提示，该技能会发现候选集，进行广泛的分类（按模块/组件分组，识别影响最大的集群），并在深入调查之前推荐一个起始区域。

＃＃ 参考

＃＃ 常问问题

更新和替换有什么区别？ 更新修复了偏差，同时保持核心解决方案完整（重命名文件、移动类、损坏的链接）。替换重写了指南，因为推荐的方法发生了重大变化。边界：如果您发现自己重写了解决方案部分，那就是替换，而不是更新。

为什么该技能不询问代码更改是否是有意的？ 保持在自己车道上的纪律。该技能的工作是文档准确性——将文档与当前代码相匹配。代码更改是对是错是代码审查的一个问题；如果用户认为代码错误，那就是一个单独的工作流程。

我什么时候应该使用自动修复模式？ 对于定期扫描、定期维护运行或大范围审查来说，针对每个问题都停下来是不切实际的。 Autofix 将不明确的案例标记为过时的案例，而不是错误地解决它们，因此交付的内容是一个可供人类查看的独立报告。

如果技能想要删除我认为应该保留的文档怎么办？ 在交互模式下，您将在删除之前看到带有证据的建议。拒绝，医生留下来。在自动修复模式下，自动删除安全条件是保守的——实质性引用会自动降级为过时标记。

为什么要删除而不是存档？ 存档文件夹会累积并污染搜索结果，没有人会阅读它们，并且它们会产生“我们会回到这个问题”的错觉，但实际上却没有这样做。 Git 历史记录会保留每个已删除的文件。 git log --diff-filter=D -- docs/solutions/ 找到您需要恢复的任何内容。

Does it handle pattern docs differently from learning docs? Yes — pattern docs are derived guidance, not incident-level learnings. The five outcomes apply, but with different evidence: Keep means underlying learnings still support the rule; Replace means the synthesis is misleading and a different generalization is needed based on refreshed learnings.

另请参阅

• ce-compound — 获取新知识；该技能维持现有的集合
• ce-plan — 将 docs/solutions/ 读取为机构内存；受益于干净、最新的文档
• ce-ideate — 在接地期间也参考 docs/solutions/
• ce-doc-review — 不同的技能：基于角色的单个文档审查，而不是跨集合的维护