ce:compound-refresh

Compound Refresh

长期维护 docs/solutions/ 的质量。此工作流会根据当前代码库审查已有经验总结，然后刷新依赖这些总结的派生模式文档。

模式检测

检查 $ARGUMENTS 是否包含 mode:autofix。如果包含，请从参数中移除它（将剩余内容用作范围提示），并以 自动修复模式 运行。

模式	适用情况	行为
交互模式（默认）	用户在线且能够回答问题	针对有歧义的情况询问用户决策，并确认操作
自动修复模式	参数中包含 mode:autofix	不与用户交互。应用所有明确无误的操作（保留、更新、合并、自动删除、有充分证据时替换）。将有歧义的情况标记为过时。最后生成摘要报告。

自动修复模式规则

• 跳过所有用户问题。 绝不暂停等待输入。
• 处理范围内的所有文档。 不询问是否缩小范围——如果未提供范围提示，则处理全部文档。
• 尝试所有安全操作： 保留（不做更改）、更新（修正引用）、合并（合并并删除被取代的文档）、自动删除（满足明确无误的条件）、替换（证据充分时）。如果写入成功，则记录为已应用。如果写入失败（例如，权限被拒绝），则在报告中将该操作记录为建议并继续——不要停止，也不要请求权限。
• 不确定时标记为过时。 如果分类存在实质性歧义（更新还是替换、合并或删除），或替换的证据不足，则在 frontmatter 中添加 status: stale、stale_reason 和 stale_date，将其标记为过时。如果标记过时的写入也失败，则将其列为建议。
• 采取保守的置信度标准。 在交互模式中，遇到边界情况时向用户提问。在自动修复模式中，遇到边界情况时标记为过时。宁可标记为过时，也不要错误操作。
• 始终生成报告。 报告是主要交付内容，分为两个部分：已应用（成功写入的操作）和建议（无法写入的操作，并提供完整理由，方便人工应用或交互式运行此技能）。无论获得了哪些权限，报告结构都相同——区别仅在于各操作归入哪个部分。

交互原则

这些原则仅适用于交互模式。在自动修复模式中，跳过所有用户问题，并应用上述自动修复模式规则。

遵循与 ce:brainstorm 相同的交互方式：

• 一次只问一个问题——如果平台提供阻塞式提问工具，则使用该工具（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）。否则，以纯文本呈现带编号的选项，并等待用户回复后再继续
• 存在自然选项时，优先使用多项选择
• 先了解范围和意图，仅在必要时逐步缩小范围
• 掌握证据之前，不要要求用户做决定
• 先给出建议，并简要说明理由

目标不是让用户逐项完成清单，而是以尽可能低的阻力，帮助用户做出良好的维护决策。

刷新顺序

按以下顺序刷新：

1. 首先审查相关的单项经验总结文档
2. 记录哪些经验总结仍然有效、已更新、已合并、已替换或已删除
3. 然后审查依赖这些经验总结的模式文档

原因：

• 经验总结文档是主要依据
• 模式文档由一份或多份经验总结派生而来
• 过时的经验总结可能让模式看起来比实际更有效

如果用户一开始就指定了某个模式文档，你可以先从该文档入手了解问题，但在更改模式文档之前，先检查其支持性经验总结文档。

维护模型

对每个候选资料进行分类，归入以下五种结果之一：

结果	含义	默认操作
保留	仍然准确且有用	默认不编辑文件；报告已完成审核，且内容仍可信
更新	核心解决方案仍然正确，但引用内容已过时	根据证据直接修改原文
整合	两篇或更多文档内容高度重叠，但都正确	将独有内容合并到规范文档中，然后删除被合并的文档
替换	旧资料如今会造成误导，但已有明确的更佳替代方案	创建可信的后继资料，然后删除旧资料
删除	已不再有用、适用或具有独特价值	删除文件——如需恢复，任何人都可以从 git 历史中找回

核心规则

1. 证据为判断提供依据。 以下信号是输入，而非机械评分表。运用工程判断，决定该文档是否仍然可信。
2. 优先选择不写入的 Keep。 不要只为留下审查记录而更新文档。
3. 让文档符合现实，而不是反过来。 如果当前代码与某条经验不符，就更新经验以反映当前代码。此技能的职责是确保文档准确，而非审查代码——不要询问用户代码更改是否「有意为之」或「属于回归」。代码变了，文档就应与之相符。如果用户认为代码有问题，那是此工作流之外的另一个问题。
4. 果断处理，尽量少问。 当证据明确时（文件已重命名、类已移动、引用已失效），直接应用更新。在交互模式下，只有在正确操作确实存在歧义时才询问用户。在自动修复模式下，将有歧义的情况标记为过时，而不是提问。目标是自动维护，由人工监督需要判断的情况，而不是每发现一处问题就提问。
5. 避免低价值变动。 不要只为修正错字、润色措辞或进行无法实质提升准确性或可用性的表面修改而编辑文档。
6. 仅在存在有意义且有证据支持的偏差时使用 Update。 如果修正路径、模块名称、相关链接、类别元数据、代码片段或明显过时的措辞能实质提升准确性，这些内容都可以修改。
7. 仅在确有替代方案时使用 Replace。 这意味着符合以下任一条件：
   • 当前对话中包含最近已解决且经过验证的替代修复方案；或
   • 用户提供了足够具体的替代方案背景，能够如实记录后继方案；或
   • 代码库调查找到了当前方案，并能将其记录为后继方案；或
   • 更新的文档、模式文档、PR 或问题提供了有力的后继方案证据。
8. 代码不存在时就删除。 如果被引用的代码、控制器或工作流在代码库中已不存在，且找不到后继方案，就删除文件——不要仅仅因为一般性建议仍然「合理」就默认选择 Keep。关于已删除功能的经验会误导读者，让他们以为该功能仍然存在。在 Keep 和 Delete 之间犹豫不决时，在交互模式下询问用户，在自动修复模式下标记为过时。但被引用的文件缺失且找不到匹配代码，不属于需要犹豫的情况——这是明确无误的 Delete 证据。自动删除。
9. 评估文档集的设计，而不只检查准确性。 除了检查每份文档是否准确，还要评估它是否仍然适合作为知识单元。如果两份或更多文档内容高度重叠，应判断它们是应保持独立、明确划分范围，还是合并为一份规范文档。冗余文档很危险，因为它们会悄然偏离——两份内容相同的文档最终会变得不一致。
10. 删除，不要归档。 没有 _archived/ 目录。当文档不再有用时，就删除它。Git 历史会保留所有已删除的文件——那就是归档。专门的归档目录会造成问题：归档文档不断累积、污染搜索结果，而且没人会看。如果有人需要已删除的文档，可以用 git log --diff-filter=D -- docs/solutions/ 找到它。

范围选择

首先，查找 docs/solutions/ 下的经验总结和模式文档。

排除：

• README.md
• docs/solutions/_archived/（遗留目录——如果存在，请在报告中标记以便清理）

查找 docs/solutions/ 下所有 .md 文件，排除 README.md 文件以及 _archived/ 下的所有文件。如果存在 _archived/ 目录，请在报告中注明它是应清理的遗留产物（文件应恢复或删除）。

如果提供了 $ARGUMENTS，请先用它缩小范围，再继续。按以下顺序尝试匹配策略，遇到第一个产生结果的策略时停止：

1. 目录匹配 — 检查参数是否与 docs/solutions/ 下的子目录名称匹配（例如，performance-issues、database-issues）
2. Frontmatter 匹配 — 在经验总结的 frontmatter 中搜索 module、component 或 tags 字段，查找参数
3. 文件名匹配 — 按文件名匹配（允许部分匹配）
4. 内容搜索 — 在文件内容中搜索参数作为关键词（适用于功能名称或功能领域）

如果没有找到匹配项，请报告这一情况并请用户澄清。在自动修复模式下，报告未找到匹配项并停止——不要猜测范围。

如果没有找到候选文档，请报告：

No candidate docs found in docs/solutions/.
Run `ce:compound` after solving problems to start building your knowledge base.

阶段 0：评估并选择处理路径

在要求用户进行分类之前：

1. 找出候选产物
2. 估算范围
3. 选择适合当前情况、交互最少的处理路径

按范围选择处理路径

范围	适用情况	交互方式
聚焦	可能涉及 1–2 个文件，或用户指定了某篇文档	直接调查，然后给出建议
批量	最多约 8 篇大多互相独立的文档	先调查，再分组给出建议
广泛	9 篇以上文档、范围模糊，或需要扫描整个代码库中的过时文档	先分类，再分批调查

广泛范围的初步分类

当范围较广（候选文档 9 篇以上）时，请在深入调查前进行轻量级分类：

1. 清点 — 阅读所有候选文档的 frontmatter，按模块、组件或类别分组
2. 影响聚类 — 找出经验总结和模式文档最密集的领域。覆盖同一模块的 5 篇经验总结和 2 篇模式文档构成的聚类，其影响高于 5 个各只有一篇文档的独立领域，因为一篇文档过时很可能会影响其他文档。
3. 抽查偏差 — 对每个聚类，检查主要引用的文件是否仍然存在。高影响聚类中存在失效引用，是判断从何处着手的最强信号。
4. 建议起始领域 — 简要说明理由，给出影响最大的聚类，并询问用户是确认还是调整方向。在自动修复模式下，跳过提问，按影响程度处理所有聚类。

示例：

Found 24 learnings across 5 areas.

The auth module has 5 learnings and 2 pattern docs that cross-reference
each other — and 3 of those reference files that no longer exist.
I'd start there.

1. Start with auth (recommended)
2. Pick a different area
3. Review everything

暂时不要询问用户选择操作。先收集证据。

阶段 1：调查候选经验

对于范围内的每条经验，阅读内容，将其中的说法与当前代码库交叉核对，并给出建议。

一条经验有多个可能独立过时的维度。表层检查能发现明显的偏差，但过时之处往往藏得更深：

• 引用 — 提到的文件路径、类名和模块是否仍然存在，还是已经移至别处？
• 建议的解决方案 — 修复方案是否仍符合当前代码的实际工作方式？文件改了名，但实现模式完全不同，这就不只是更新路径。
• 代码示例 — 如果经验包含代码片段，它们是否仍反映当前实现？
• 相关文档 — 交叉引用的经验和模式是否仍然存在且保持一致？
• 自动记忆（仅限 Claude Code）— 系统提示词中注入的自动记忆块，是否包含同一问题领域的条目？直接检查该记忆块。如果没有记忆块，则跳过此维度。描述了与经验建议不同方法的记忆说明，是补充性的偏差信号。
• 重叠 — 调查期间，注意范围内是否有其他文档涉及相同问题领域、引用相同文件或建议类似解决方案。对于每处重叠，记录：两个文件路径、重叠维度（问题、解决方案、根本原因、文件、预防措施），以及哪篇文档覆盖面更广或更新。这些信号会用于阶段 1.75（文档集分析）。

调查深度应与经验的具体程度相匹配——引用确切文件路径和代码片段的经验，需要比描述一般原则的经验更多的核验。

偏差分类：更新还是替换

关键在于区分偏差是表面性的（引用位置变了，但解决方案不变），还是实质性的（解决方案本身发生了变化）：

• 更新范畴 — 文件路径变了、类重命名了、链接失效了、元数据过时了，但核心建议仍符合代码的工作方式。ce:compound-refresh 可直接修复这些问题。
• 替换范畴 — 建议的解决方案与当前代码冲突、架构方法发生变化，或该模式已不再是首选方式。这意味着需要编写一条新经验。替换子 Agent 会根据 ce:compound 的文档格式（前言、问题、根本原因、解决方案、预防措施）编写后继文档，并使用已收集的调查证据。编排器不会直接重写经验，而是委托子 Agent 执行，以隔离上下文。

**分界线：**如果你发现自己需要重写解决方案章节或更改经验的建议，就应停止——这属于替换，而非更新。

来自记忆的偏差信号仅作补充，并非主要依据。单凭一条描述了不同方法的记忆说明，不足以判定为替换或删除。利用记忆信号来：

• 印证来自代码库的偏差（强化替换的理由）
• 在代码库证据模棱两可时，提示进行更深入的调查
• 在证据报告中补充背景信息（“（Claude 自动记忆）中的说明表明，自本经验编写以来，方法 X 可能已发生变化”）

在自动修复模式下，如果偏差仅来自记忆（没有代码库证据佐证），则应标记为过时，而不采取操作。

判断指南

以下三条指南容易被误解：

1. 矛盾 = 强烈的替换信号。 如果某条经验的建议与当前代码模式或近期验证过的修复相冲突，这就不是轻微偏差，而是该经验正在误导读者。应归类为替换。
2. 仅凭时间久远不能判定为过时。 一条两年前的经验如果仍与当前代码一致，就是可用的。时间久远只能作为提醒，促使你更仔细地检查。
3. 删除前先检查是否有后续文档。 在建议替换或删除之前，先查找是否有更新的经验、模式文档、PR 或 issue 涵盖了相同的问题领域。如果有后续内容，应优先选择替换而非删除，以便引导读者查阅更新的指南。

阶段 1.5：调查模式文档

审核底层经验文档后，调查 docs/solutions/patterns/ 下任何相关的模式文档。

模式文档影响面大——与单条经验过时相比，模式过时的危害更大，因为后续工作可能会将其视为广泛适用的指南。请根据其所依赖的经验更新后的状态，评估其中的概括性规则是否仍然成立。

缺少明确支撑经验的模式文档是一个过时信号——在保持原样之前，应仔细调查。

阶段 1.75：文档集分析

调查完单篇文档后，退一步从整体上评估文档集。目标是发现只有相互对比时才会显现的问题，而不只是检查文档是否符合实际情况。

重叠检测

对于模块、组件、标签或问题领域相同的文档，请从以下维度进行比较：

• 问题陈述——它们描述的是同一个根本问题吗？
• 解决方案形式——即使措辞不同，它们建议的是同一种方法吗？
• 引用的文件——它们指向相同的代码路径吗？
• 预防规则——它们重复了相同的预防要点吗？
• 根本原因——它们指出的是相同的根本原因吗？

在 3 个或更多维度上高度重叠，是强烈的合并信号。需要思考的问题是：“未来的维护者是否需要同时阅读两篇文档才能了解当前的准确信息，还是其中一篇大多在重复另一篇的内容？”

取代信号

识别“较早的窄范围前身，较新的规范文档”模式：

• 较新的文档涵盖了相同的文件、相同的工作流，并更广泛地说明了运行时行为
• 较早的文档描述了某个具体事件，而较新的文档将其概括为一种模式
• 两篇文档建议相同的修复，但较新文档的背景、示例或范围更完善

如果较新的文档显然涵盖了较早文档的全部内容，那么较早文档就是合并候选项——应将其独有内容（如果有）合并到较新的文档中，并删除较早的文档。

确定规范文档

对于每个主题组（即共享问题领域的文档），确定哪篇文档是规范信息来源：

• 通常是该组中最新、范围最广且最准确的文档
• 维护者搜索该主题时应该首先找到的文档
• 其他文档应该指向它，而不是重复其内容

该组中的其他文档属于以下类别之一：

• 独立文档——涵盖有实质差异的子问题，具有独立的检索价值。应单独保留。
• 已涵盖——其独有内容可作为一个章节纳入规范文档。应合并。
• 冗余——没有提供规范文档中未包含的内容。应删除。

检索价值测试

在建议将两份文档分开保留之前，请先进行此项测试：“如果维护者六个月后搜索这个主题，将它们分成单独的文档会提升内容的可发现性，还是只会带来内容偏离的风险？”

只有在以下情况下，单独成文才有价值：

• 它们涵盖真正不同的子问题，用户可能会分别搜索
• 它们面向不同的受众或场景（例如，一份讲调试，另一份讲预防）
• 合并后会形成一份难以浏览的冗长文档，不如保留两份重点明确的文档

如果以上情况都不适用，应优先合并。两份涵盖相同内容的文档最终会逐渐偏离并相互矛盾——这比一份稍长的文档更糟。

跨文档冲突检查

检查范围内的文档是否存在明显矛盾：

• 文档 A 说“始终使用方法 X”，而文档 B 说“避免使用方法 X”
• 文档 A 引用了文档 B 标记为已弃用的文件路径
• 文档 A 和文档 B 对看似相同的问题给出了不同的根本原因

文档之间的矛盾比单份文档过时更紧迫——它们会直接误导读者。应立即标记并解决，可通过合并（如果一份是另一份对同一事实的过时描述）或有针对性的更新/替换来处理。

子 Agent 策略

调查多个内容时，应根据上下文隔离的需要使用子 Agent，而不是仅仅因为任务听起来复杂。选择适用的最轻量方案：

方案	适用情况
仅在主线程中处理	范围较小，文档较短
顺序调用子 Agent	1-2 个内容，需要读取大量支持文件
并行调用子 Agent	3 个或更多真正独立且重叠较少的内容
分批调用子 Agent	大范围检查——先缩小范围，再分批调查

启动任何子 Agent 时，省略 mode 参数，以便应用用户配置的权限设置。在其任务提示中加入以下指示：

所有调查都使用专用的文件搜索和读取工具（Glob、Grep、Read）。不要使用 shell 命令（ls、find、cat、grep、test、bash）进行文件操作。这样可以避免权限提示，也更加可靠。

另请扫描注入系统提示的“用户自动记忆”区块（仅限 Claude Code）。检查是否有与该学习内容的问题领域相关的笔记。请在证据部分单独报告来自记忆的偏离信号，并标注“(auto memory [claude])”。如果上下文中没有此区块，则跳过此项检查。

有两种子 Agent 角色：

1. 调查子 Agent — 只读。不得编辑文件、创建替代内容或删除任何内容。每个子 Agent 都应返回：文件路径、证据、建议操作、置信度和待解决问题。内容彼此独立时，可并行执行。
2. 替换子 Agent — 编写一份新的学习内容以替换过时内容。此类任务应一次一个，按顺序执行（每个替换子 Agent 可能都需要阅读大量代码，并行运行可能耗尽上下文）。每次替换完成后，由协调者负责所有删除和元数据更新。

协调者汇总调查结果、检测矛盾、协调替换子 Agent，并集中执行所有删除和元数据编辑。在交互模式下，对于模棱两可的情况，应向用户提问。在自动修复模式下，则将模棱两可的内容标记为过时。如果两个内容有重叠或讨论同一根本问题，应一起调查，而不是并行处理。

阶段 2：确定合适的维护操作

收集证据后，指定一项建议操作。

保留

学习内容仍然准确且有用。不要编辑文件——报告已完成审查，内容仍可信。仅当你已因其他原因进行有意义的更新时，才添加 last_refreshed。

更新

核心解决方案仍然有效，但其中的引用已经过时（路径、类名、链接、代码片段、元数据）。直接应用修正。

合并

当第 1.75 阶段发现文档内容高度重叠且都基本正确时，选择合并。这不同于更新（修正文档中的过时内容）和替换（重写误导性指导）。合并用于处理“两个都对，但其中一个涵盖了另一个”的情况。

适合合并的情况：

• 两篇文档描述相同的问题，并推荐相同或兼容的解决方案
• 一篇文档是范围较窄的前置内容，较新的文档则更全面地涵盖了相同内容
• 被包含文档中的独有内容可以作为一个章节或补充内容加入规范文档
• 保留两篇文档会增加内容过时的风险，却不会显著提升检索价值

不适合合并的情况（应用第 1.75 阶段的检索价值测试）：

• 文档涵盖真正不同的子问题，用户会分别搜索这些问题
• 合并会使文档变得难以使用，其对导航的损害超过内容过时风险对准确性的损害

合并与删除： 如果被包含的文档有值得保留的独有内容（边缘情况、替代方案、额外的预防规则），先用合并操作整合这些内容。如果被包含的文档没有补充规范文档中尚未包含的内容，则直接删除。

合并操作：将被包含文档中的独有内容并入规范文档，然后删除被包含的文档。不要归档——直接删除。Git 历史会保留它。

替换

当这项经验的核心指导如今已具有误导性时，选择替换——推荐的修复方案发生了重大变化、根本原因或架构已改变，或更适合采用其他模式。

用户可能在原始经验写成数月后才调用刷新流程。不要向他们询问他们可能并不了解的替换背景——利用 Agent 的能力调查代码库并综合出替代方案。

证据评估：

在你确定某项内容需要替换时，第 1 阶段的调查已经收集了大量证据：旧经验中的说法、当前代码的实际行为，以及内容过时的原因。评估这些证据是否足以撰写可信的替代内容：

• 证据充足 — 你既了解旧经验推荐了什么，也了解当前采用的方法。调查发现了当前的代码模式、新的文件位置以及架构变化。→ 撰写替代内容（参见第 4 阶段的替换流程）。
• 证据不足 — 变化非常根本，以至于你无法有把握地记录当前方法。整个子系统已被替换，或仅靠扫描文件无法理解新架构。→ 在原位置将其标记为过时：
  • 在 frontmatter 中添加 status: stale、stale_reason: [what you found]、stale_date: YYYY-MM-DD
  • 报告你找到的证据以及缺少的内容
  • 建议用户在下次处理该领域并掌握最新的问题解决背景时，运行 ce:compound

删除

在以下情况下选择删除：

• 相关代码或工作流已不存在，问题领域也已消失
• 该经验已过时，且没有值得记录的现代替代方案
• 该经验与另一篇文档完全重复（如果有独有内容需要先合并，则使用合并）
• 没有有意义的后续证据表明应当替换它

操作：删除文件。不要创建归档目录，也不要添加元数据——直接删除即可。如果需要恢复，Git 历史会保留所有已删除的文件。

删除前：检查问题领域是否仍然存在

当某条学习记录引用的文件已不存在时，这是有力证据——但只能说明实现已不存在。删除前，请判断这条学习记录要解决的问题是否仍然是代码库中的一项关注点：

• 一条关于会话令牌存储的学习记录中，auth_token.rb 已不存在——应用程序是否仍会处理会话令牌？如果是，那么这个概念仍然存在，只是采用了新的实现。这应归类为替换，而不是删除。
• 一条关于已弃用 API 端点的学习记录中，整个功能都已移除——问题领域已不存在。这应归类为删除。

不要机械地搜索旧学习记录中的关键词。相反，应先理解这条学习记录要解决什么问题，再调查代码库中是否仍存在该问题领域。Agent 能理解概念——利用这种理解，寻找问题现在所在的位置，而不是旧代码曾经所在的位置。

只有在实现和问题领域都已不复存在时，才自动删除：

• 引用的代码已不存在，而且应用程序不再涉及该问题领域
• 这条学习记录已被明显更好的后续内容完全取代，而且旧文档没有提供独特价值
• 该文档显然是冗余的，没有补充权威文档尚未说明的内容

如果实现已不存在，但问题领域仍然存在（应用仍会进行身份验证、处理付款或处理迁移），则归类为替换——这个问题仍然重要，应记录当前采用的方法。

不要仅仅因为某条学习记录中的一般性建议“仍然正确”就保留它——如果其中引用的具体代码已不存在，这条学习记录就会误导读者。但如果问题领域仍然存在，也不要删除该学习记录——应通过替代内容填补这一知识空白。

模式指南

对模式文档应用相同的五种处理方式（保留、更新、合并、替换、删除），但应将其视为归纳得出的指导原则，而非事件级学习记录。主要区别如下：

• 保留：底层学习记录仍然支持该通用规则，且示例仍具有代表性
• 更新：规则仍然成立，但示例、链接、范围或支持性引用已过时
• 合并：两篇模式文档归纳了相同的一组学习记录，或涵盖相同的设计关注点——将其合并为一篇权威模式文档
• 替换：通用规则如今具有误导性，或底层学习记录支持另一种归纳结论。替代内容应基于更新后的学习记录集合——不要凭空臆造新规则
• 删除：该模式已不再有效、不再反复出现，或已被更完善的模式文档完全涵盖，且不再包含独特内容

第 3 阶段：征求决策

自动修复模式

跳过整个阶段。不要提问，不要提供选项，也不要等待输入。 直接进入第 4 阶段，并根据第 2 阶段的分类执行所有操作：

• 明确无误的保留、更新、合并、自动删除，以及证据充分的替换 → 直接执行
• 有歧义的情况 → 标记为过时
• 然后生成报告（参见输出格式）

交互模式

大多数更新和合并都应直接执行，无需提问。仅在以下情况下询问用户：

• 正确的处理方式确实存在歧义（更新、替换、合并还是删除）
• 即将删除一份文档，且证据不明确（参见第 2 阶段的自动删除标准）。符合自动删除标准时，无需询问，直接执行。
• 即将合并文档，但无法明确判断应选择哪篇作为权威文档
• 即将通过替换创建后续文档

不要询问代码更改是否出于有意、用户是否想修复代码中的错误，或其他超出文档维护范围的问题。专注于本职工作——确保文档准确。

问题风格

如果平台提供阻塞式提问工具，请始终使用该工具呈现选项（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）。否则，请用纯文本列出编号选项，并等待用户回复后再继续。

问题规则：

• 一次只问一个问题
• 优先采用多选题
• 将推荐选项放在最前面
• 用一句简洁的话说明推荐理由
• 避免让用户从实际不可行的操作中做选择

聚焦范围

针对单个工件，请提供：

• 文件路径
• 2-4 条证据
• 推荐操作

然后询问：

This [learning/pattern] looks like a [Keep/Update/Consolidate/Replace/Delete].

Why: [one-sentence rationale based on the evidence]

What would you like to do?

1. [Recommended action]
2. [Second plausible action]
3. Skip for now

除非五种操作都确实可行，否则不要全部列出。

批量范围

对于多项经验：

1. 将明显应当保留的情况归为一组
2. 将明显应当更新且修复方式简单的情况归为一组
3. 对照规范文档明确的情况，一起提出合并
4. 替换应逐项或分成很小的组提出
5. 删除应逐项提出，除非它们明显适合自动删除

分阶段征求确认：

1. 确认分组的保留/更新建议
2. 然后处理合并组（说明规范文档，以及要合并哪些内容）
3. 逐项处理替换
4. 逐项处理删除，除非删除明确且可安全自动执行

广泛范围

如果用户要求全面更新，请分步推进：

1. 先缩小范围
2. 调查适量的一批内容
3. 提出建议
4. 询问是否继续处理下一批

不要一开始就把完整的维护队列全部摆给用户。

第 4 阶段：执行选定的操作

保留流程

默认不编辑文件。概述该经验仍然可信的原因。

更新流程

只有在解决方案实质上仍然正确时，才进行原位编辑。

有效的原位更新示例：

• 将对 app/models/auth_token.rb 的引用改为 app/models/session_token.rb
• 将 module: AuthToken 更新为 module: SessionToken
• 修正指向相关文档的过时链接
• 目录迁移后更新实现说明

以下情况不应进行原位更新：

• 修正不会影响理解的错别字
• 仅为改善文风而改写措辞
• 不会实质提升准确性或可用性的小幅清理
• 旧的修复方法如今已成为反模式
• 系统架构变化太大，导致旧指导具有误导性
• 故障排查路径发生了重大变化

这些情况应当替换，而不是更新。

Consolidate 流程

协调器直接处理整合（无需子 Agent——文档已读完，合并只是有针对性的编辑）。按主题集群处理 Consolidate 候选项。针对 Phase 1.75 中识别出的每个集群：

1. 确认规范文档——集群中覆盖范围更广、内容更新且准确性更高的文档。
2. 提取独有内容，即被合并文档中规范文档尚未涵盖的内容。这可能是特定边缘情况、额外的预防规则或其他调试方法。
3. 将独有内容合并到规范文档的自然位置。不要只把内容附加在末尾，而应将其整合到逻辑上合适的位置。如果独有内容较少（一个项目符号、一句话），就直接融入正文。如果是一个较大的子主题，则添加一个标题清晰的章节。
4. 更新交叉引用——如果其他文档引用了被合并的文档，请更新这些引用，使其指向规范文档。
5. 删除被合并的文档。 不要归档，也不要添加重定向元数据——直接删除文件即可。Git 历史会保留它。

如果一个文档集群有 3 个或更多重叠文档，请逐对处理：先整合重叠程度最高的两个文档，然后再评估合并后的结果是否应与下一个文档整合。

超出合并范围的结构调整： Consolidate 也涵盖反向情况。如果一篇文档内容过于庞杂，涉及多个不同问题，而将其拆分有助于检索，那么建议拆分也是合理的。只有在各子主题确实相互独立，且维护者可能只搜索其中一个、无需了解另一个时，才这样做。

Replace 流程

按顺序逐个处理 Replace 候选项。每次替换都由子 Agent 编写，以保护主上下文窗口。

需要替换时，请阅读文档契约文件，并将其内容传入替换子 Agent 的任务提示词：

• references/schema.yaml — frontmatter 字段和枚举值
• references/yaml-schema.md — 类别映射
• assets/resolution-template.md — 章节结构

不要让替换子 Agent 凭记忆自行编造 frontmatter 字段、枚举值或章节顺序。

证据充分时：

1. 启动一个子 Agent 来编写替换后的学习文档。向其提供：
   • 旧学习文档的完整内容
   • 调查证据摘要（发生了什么变化、当前代码如何运行、为什么旧指引会造成误导）
   • 目标路径和类别（除非类别本身发生变化，否则与旧学习文档的类别相同）
   • 上述三个支持文件中的相关内容
2. 子 Agent 使用支持文件作为事实依据来编写新学习文档：references/schema.yaml 用于确认 frontmatter 字段和枚举值，references/yaml-schema.md 用于确认类别映射，assets/resolution-template.md 用于确认章节顺序。如果还需要传入内容之外的上下文，应使用专用的文件搜索和读取工具。
3. 子 Agent 完成后，协调器删除旧学习文件。新学习文档的 frontmatter 可以包含 supersedes: [old learning filename] 以便追溯，但这是可选的——Git 历史和提交消息能提供相同信息。

证据不足时：

1. 在原文档中将学习文档标记为过时：
   • 在 frontmatter 中添加：status: stale、stale_reason: [what you found]、stale_date: YYYY-MM-DD
2. 报告已找到的证据和缺失的信息
3. 建议用户下次遇到该领域的问题后运行 ce:compound

Delete 流程

仅在学习文档明确过时、内容重复（且没有独有内容可合并）或其问题领域已不存在时才删除。不要仅仅因为文档年代久远就删除它——文档年限本身并非判断依据。

输出格式

必须以 Markdown 格式输出完整报告。 不要在内部总结发现后只输出一句话。报告就是交付内容——请完整输出每个部分，并使用标题、表格和项目符号格式清晰呈现。

处理完所选范围后，输出以下报告：

Compound Refresh Summary
========================
Scanned: N learnings

Kept: X
Updated: Y
Consolidated: C
Replaced: Z
Deleted: W
Skipped: V
Marked stale: S

然后，列出处理过的每个文件：

• 文件路径
• 分类（Keep/Update/Consolidate/Replace/Delete/Stale）
• 找到的证据——任何来自记忆的发现都要标注“（auto memory [claude]）”，以便与来自代码库的证据区分
• 已采取的操作（或建议采取的操作）
• 对于 Consolidate：注明哪个文档是规范文档、合并了哪些独有内容，以及删除了哪些内容

对于 Keep 结果，请将其列在“已审查但未编辑”部分下，以便呈现结果且不造成不必要的 git 变更。

自动修复模式报告

在自动修复模式下，报告是唯一的交付内容——没有用户可以提出后续问题，因此报告必须完整自足。请输出完整报告。不要缩写、总结或跳过任何部分。

将操作分为两个部分：

已应用（成功写入的更改）：

• 对于每个 Updated 文件：文件路径、修复了哪些引用，以及原因
• 对于每个 Consolidated 文档组：规范文档、从每个被合并文档中合并的独有内容，以及已删除的被合并文档
• 对于每个 Replaced 文件：旧的学习内容建议了什么、当前代码实际执行什么，以及新后继文档的路径
• 对于每个 Deleted 文件：文件路径及删除原因（例如，问题领域已不存在、内容完全重复等）
• 对于每个 Marked stale 文件：文件路径、找到的证据，以及原因存在歧义

建议（无法写入的操作，例如权限被拒绝）：

• 详细程度同上，但应以建议人工执行的方式表述
• 提供足够的上下文，让用户可以手动应用更改或以交互方式重新运行该技能

如果所有写入都成功，“建议”部分为空。如果没有写入成功（例如，以只读方式运行），则所有操作都列在“建议”部分——此时报告将成为维护计划。

历史文档清理（如果 docs/solutions/_archived/ 存在）：

• 列出找到的归档文件，并建议其处置方式：恢复（如果仍然相关）、删除（如果确实已过时）或合并（如果与现有文档重叠）

阶段 5：提交更改

执行完所有操作并生成报告后，处理更改的提交。如果没有修改任何文件（全部为 Keep，或所有写入均失败），则跳过此阶段。

检测 git 上下文

提供选项前，请检查：

1. 当前检出的分支（main/master 还是功能分支）
2. 工作区中是否存在 compound-refresh 修改范围之外的其他未提交更改
3. 最近的提交消息，以匹配仓库的提交风格

自动修复模式

使用合理的默认选项——没有用户可以询问：

上下文	默认操作
位于 main/master	创建一个以刷新内容命名的分支（例如，docs/refresh-auth-and-ci-learnings），提交更改，并尝试创建 PR。如果 PR 创建失败，请报告分支名称。
位于功能分支	在当前分支上单独创建一次提交
git 操作失败	在报告中附上建议使用的 git 命令并继续

只暂存 compound-refresh 修改过的文件——不要暂存工作区中的其他脏文件。

交互模式

首先，运行 git branch --show-current 以确定当前分支。然后根据结果提供正确的选项。无论用户选择哪个选项，都只暂存 compound-refresh 文件。

如果当前分支是 main、master 或仓库的默认分支：

1. 创建分支、提交并发起 PR（推荐）——分支名称应具体说明刷新了什么，而非使用通用名称（例如，docs/refresh-auth-learnings，而非 docs/compound-refresh）
2. 直接提交到 {current branch name}
3. 不提交——由我处理

如果当前分支是功能分支，且工作区干净：

1. 将更改作为单独提交提交到 {current branch name}（推荐）
2. 创建单独的分支并提交
3. 不提交

如果当前分支是功能分支，且工作区不干净（存在其他未提交的更改）：

1. 仅将 compound-refresh 更改提交到 {current branch name}（选择性暂存——其他有更改的文件保持不变）
2. 不提交

提交消息

编写描述性提交消息，要求：

• 概述刷新了什么（例如，“更新 3 条过时的经验总结，整合 2 篇重复文档，删除 1 篇已过时文档”）
• 遵循仓库现有的提交规范（检查近期 git log，了解其风格）
• 简洁明了——详情已在更改的文件中说明

与 ce:compound 的关系

• ce:compound 记录新近解决且已验证的问题
• ce:compound-refresh 随代码库演进维护旧有经验总结，包括确保其各自内容准确，以及作为文档集的整体设计合理

只有当刷新过程有足够的实际证据，能够撰写可信的后继内容时，才使用 Replace。证据不足时，应标记为过时，并建议用户下次遇到该问题领域时使用 ce:compound。

当文档集不断自然增长并逐渐出现冗余时，应主动使用 Consolidate。每次调用 ce:compound 都会新增一篇文档——随着时间推移，多篇文档可能从略有差异的角度描述同一问题。定期整合可让文档集保持精简且权威。

可发现性检查

生成刷新报告后，检查项目的指令文件是否会引导 Agent 在开始处理已记录的领域之前，发现并搜索 docs/solutions/。每次都要执行此检查——只有当 Agent 能找到知识库时，它才能不断发挥价值。如果检查导致文件发生更改，应在 Phase 5 的提交流程中提交，或紧随其后提交——见下文第 5 步。

1. 确认根目录下存在哪些指令文件（AGENTS.md、CLAUDE.md，或两者都有）。读取这些文件，并确定哪个文件包含实质性内容——其中一个文件可能只是通过 @ 引入另一个文件的垫片（例如，CLAUDE.md 仅包含 @AGENTS.md，反之亦然）。实质性文件是评估和编辑的目标；忽略垫片。如果两个文件都不存在，则完全跳过此检查。

2. 评估 Agent 阅读指令文件后是否能了解以下三点：

   • 存在一个可搜索的、记录了解决方案的知识库
   • 了解足以有效搜索的知识库结构信息（类别组织方式、module、tags、problem_type 等 YAML frontmatter 字段）
   • 何时搜索知识库（在已记录的领域实施功能、调试问题或做出决策之前——经验总结可能涉及 Bug、最佳实践、工作流模式或其他机构知识）

   这是语义评估，不是字符串匹配。相关信息可以是架构部分中的一行文字、注意事项部分中的一条项目符号、分散在多个位置，也可以完全不出现 docs/solutions/ 这个确切路径。请自行判断——如果 Agent 阅读文件后能合理地发现并使用知识库，则检查通过。

3. 如果已经满足这一意图，则无需采取任何行动。

4. 如果尚未满足： a. 根据文件现有的结构、语气和信息密度，确定在哪里自然地提及此内容。创建新章节之前，先检查这条信息能否作为一行内容，放入最接近的相关章节中，例如架构树、目录列表、文档章节或约定说明块。通常，在现有章节中添加一行远胜于新建标题章节。只有当文件有清晰的分节结构，且没有任何相关内容时，才最后考虑新增章节。 b. 起草尽可能精简的补充内容，传达这三项信息。与文件现有的风格和信息密度保持一致。补充内容应描述知识库本身，而不是插件。

   保持说明性语气，而非命令式语气。将时机表述为说明，而非指示——例如“在实现或调试文档涵盖的内容时可能有用”，而不是“实现或调试前先查看”。“实现前务必先搜索”之类的命令式指示会导致重复读取，因为工作流中可能已有专门的搜索步骤。目标是让 Agent 知道该目录存在及其内容，然后自行判断何时查阅。

   校准示例（不是模板，请根据文件调整）：

   如果已有目录列表或架构章节，可添加一行：

   docs/solutions/  # 过往问题的解决方案文档（bug、最佳实践、工作流模式），按类别组织，并带有 YAML frontmatter（module、tags、problem_type）
   

   如果文件中没有自然合适的位置，可以添加简短的标题章节：

   ## 已记录的解决方案
   
   `docs/solutions/` — 过往问题的解决方案文档（bug、最佳实践、工作流模式），按类别组织，并带有 YAML frontmatter（`module`、`tags`、`problem_type`）。在实现或调试文档涵盖的内容时可能有用。
   

   c. 在交互模式下，向用户说明这为何重要——在此代码库中工作的 Agent（包括新会话、其他工具，或没有该插件的协作者）不会知道应查看 docs/solutions/，除非指令文件明确提及。展示拟议的改动及其放置位置，然后使用平台提供的阻塞式提问工具（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）征求用户同意，再进行编辑。如果没有可用的提问工具，则展示提案并等待用户回复。在自动修复模式下，将其作为“可发现性建议”列入报告——不要尝试编辑指令文件（自动修复的范围是文档维护，而非项目配置）。

5. 如果检查产生了改动，则修改现有提交或创建后续提交。 如果第 4 步修改了指令文件，且第 5 阶段已经提交了刷新改动，则暂存新修改的文件，并修改现有提交（如果仍在同一分支且尚未推送），或创建一个小型后续提交（例如 docs: add docs/solutions/ discoverability to AGENTS.md）。如果第 5 阶段已经将分支推送到远程（例如分支加 PR 的流程），也要推送后续提交，以便已开启的 PR 包含可发现性改动。这样可确保运行结束时工作树干净，远程内容保持同步。如果用户在第 5 阶段选择了“不要提交”，则将指令文件的改动与其他未提交的刷新改动一起保留为未暂存状态——无需单独处理提交。