结合当前代码库，刷新仓库中沉淀的经验心得（Learnings）。用于审计过期失效、重复重叠、已被替代或发生偏离的经验记录；除非明确涉及经验知识库维护，否则请勿用于常规代码重构、排查 Debug 或 Code Review。
Compound Refresh
维持 <root>/solutions/ 目录下文档的长期质量。本工作流会将现有的经验心得（Learnings）同当前代码库进行对照复核，并同步更新依赖这些经验导出的模式文档（Pattern Docs）。
Setup
在本次调用的最开始（任何子 Agent 分派之前）执行一次此脚本，并遵循其输出的指令——除非输出指令与本 Skill 自身的“询问用户”规则相冲突（无论是仅适用于非交互模式的规则，还是全局通用的规则），此时一律以本 Skill 的规则为准，不发起任何阻塞式提问。请勿在同一次调用中重复运行；后续若发起新的 Skill 调用，会自动运行其自身的初始化脚本。若当前没有可用的 Node 运行时，Skill 将按常规逻辑继续执行。
SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi
Mode Detection
检查传入的调用参数中是否包含 mode:non-interactive 或其已废弃的别名 mode:headless。如果存在任意一个，则将其从参数列表中移除（剩余部分作为作用域提示 scope hint），并以非交互模式运行。若两个 Token 同时存在，并不构成冲突。
| 模式 | 适用场景 | 行为说明 |
|---|---|---|
| 交互模式（默认） | 用户在场且能够回答提问 | 遇模棱两可的情况提示用户决策，并在执行操作前进行确认 |
| 非交互模式 | 参数中包含 mode:non-interactive 或废弃别名 mode:headless |
无用户交互。直接自动执行所有明确无误的操作（Keep、Update、Consolidate、auto-Delete，以及证据充分时的 Replace）。模棱两可的情况直接标记为过期（stale）。最后生成汇总报告。 |
非交互模式规则
- 跳过所有用户提问。 绝不暂停等待输入。
- 处理作用域内的所有文档。 不询问缩小作用域——如果未提供 scope hint，则处理全部文档。
- 尝试所有安全操作： Keep（无操作）、Update（修复引用）、Consolidate（合并并删除被包含的文档）、auto-Delete（满足明确的删除条件）、Replace（证据充分时）。如果写入成功，记录为 Applied（已应用）。如果写入失败（如无权限），在报告中将其记录为 Recommended（建议）并继续执行——不要中断或索要权限。
- 文件迁移（Relocations）遵循自动删除模式：仅当所有条件均满足时才执行，否则记录为建议。 仅在以下 4 个条件同时满足时，才自动应用非交互式迁移：(1) Frontmatter 字段与所在目录按分类映射规则不一致；(2) 内容证据明确表明方向——是目录放错了，而不是 Frontmatter 填错了；(3) 目标分类目录已存在；(4) 所有指向该文档的引用都在仓库内部且可通过机械化重写。只要有任意条件不满足——包括内容似可归入任一分类的文档——一律将迁移操作记录在 Recommended 下。拆分文档（Splits）在非交互模式下永远只作建议：文档拆分门槛属于检索价值判断，不存在绝对标准，因此须将提议的片段边界记录在 Recommended 下。
- 不确定时标记为过期（stale）。 如果分类确实存在歧义（例如在 Update、Replace、Consolidate、Delete 之间犹豫不决），或 Replace 的证据不足，请在 Frontmatter 中标注
status: stale、stale_reason和stale_date。如果连标记 stale 的写入也失败了，同样将其作为建议写入报告。 - 采取保守的置信度态度。 在交互模式下，压线边界情况会向用户提问；而在非交互模式下，压线情况直接标记为 stale。宁可标记 stale，也绝不盲目执行潜在的错误操作。
- 始终生成汇总报告。 报告是核心交付物。报告包含两个板块：Applied（已成功写入的操作）和 Recommended（因权限不足等无法写入的操作，附带完整依据以便人工跟进或切回交互模式运行）。无论授予了什么权限，报告结构保持一致——区别仅在于各项操作落地在哪个板块。
CONCEPTS.md 引导创建请求
如果调用本 Skill 的明确目的是创建或引导生成 CONCEPTS.md（例如“创建 CONCEPTS.md”、“构建概念映射图”、“建立共享词汇表”），此时意图在“构建词汇表文件”与“运行 <root>/solutions 刷新”这两项工作之间存在歧义，因此在继续前需先澄清意图。请使用宿主平台提供的阻塞式提问工具：Claude Code 中使用 AskUserQuestion（若未加载 schema，先调用 ToolSearch 并指定 select:AskUserQuestion）、Codex 中使用 request_user_input、Antigravity CLI (agy) 中使用 ask_question、Pi 中使用 ask_user（需安装 pi-ask-user 插件）。只有在宿主环境确实不存在阻塞式工具或调用报错（例如 Codex 编辑模式）时，才退回到纯文本带序号选项——绝不能仅因为需要加载 schema 就放弃工具。严禁默默跳过提问。提供以下两个选项：
- 创建 CONCEPTS.md（构建概念映射图） —— 播种全仓库的概念映射图并提交；仅跳过 <root>/solutions 的分类阶段（阶段 0–4）。读取
references/concepts-vocabulary.md并遵循其播种目标和播种范围（全仓库）规则：从已声明的领域模型（schema、核心类型、主模型、顶层领域文档）中提取项目的核心领域名词，各项均需达标，数量由代码库决定。编写前言（参见阶段 4.5），按组织规则进行聚类，并运行可发现性检查（Discoverability Check），使AGENTS.md/CLAUDE.md能够暴露新文件。然后进入阶段 5（提交变更），通过与 Refresh 相同的持久化写入流程来提交/发起 PR 保存新的CONCEPTS.md及任何指令文件修改——切勿保持未提交状态。 - 运行刷新循环（Refresh Cycle） —— 按下文正常的刷新流程继续；若
CONCEPTS.md不存在则会进行播种，并作为阶段 4.5 的一部分进行比对对齐。
在非交互模式下由于无法向用户提问：默认执行刷新循环（词汇表无论如何都会在阶段 4.5 中完成播种与对齐），并在报告中注明未单独运行全仓库的引导创建。
Interaction Principles
以下原则仅适用于交互模式。在非交互模式下，请跳过所有用户提问，直接应用上文的非交互模式规则。
遵循与 ce-brainstorm 相同的交互风格：
- 一次只问一个问题 —— 使用宿主平台提供的阻塞式提问工具：Claude Code 中使用
AskUserQuestion（若未加载 schema 先调用ToolSearch匹配select:AskUserQuestion）、Codex 中使用request_user_input、Antigravity CLI (agy) 中使用ask_question、Pi 中使用ask_user（需要pi-ask-user扩展）。仅当宿主不存在阻塞工具或调用出错时（如 Codex 编辑模式），才回退到纯文本序号选项——不要因为需要加载 schema 就跳过工具。切勿无声无息地跳过提问 - 存在自然选项时优先使用多项选择
- 从作用域与意图切入，仅在必要时才逐步缩小范围
- 拿到证据前不要急于让用户做决定
- 先给出建议并简要解释理由
目的不是强迫用户走完一张检查清单，而是用最小的摩擦帮助他们做出良好的维护决策。
Artifact Root
本 Skill 会审查并刷新 <root>/solutions/ 路径下的经验文档。首次拼接 <root>/solutions/ 路径时解析出 <root>（按下方配置块说明）；将解析后的 <root>/solutions/ 路径传递给任何子 Agent，而非传配置原文本。
<!-- ce-docs-root:start -->
在拼接任何产物路径前，先解析出 CE 产物根目录 <root>。
- 读取
<repo-root>/.compound-engineering/config.local.yaml中的docs_root，若无则读取config.yaml；取第一个非空值（<repo-root>为git rev-parse --show-toplevel）。若均未设置 -><root>默认为docs，与此前完全一致。 - 校验已设置的值：必须是仓库相对目录，且经过软链接解析后的真实路径需留在仓库内部，既不能是仓库根目录，也不能在
.git/下。否则终止并报错指出docs_root及对应取值 -- 绝不回退至docs。 - 使用
<root>作为唯一的产物存储位置：若不存在则创建，按<root>/<subdir>格式拼接本 Skill 专用子目录的各项路径，绝不要再去读取docs。
<!-- ce-docs-root:end -->
Refresh Order
按以下顺序进行刷新：
- 先审查相关的单篇经验文档（Learning Docs）
- 记录哪些经验依然有效、被更新、被合并、被替换或被删除
- 接着审查依赖这些经验的模式文档（Pattern Docs）
为什么采用这个顺序：
- 经验文档（Learning Docs）是最基础的证据来源
- 模式文档（Pattern Docs）是从一篇或多篇经验中衍生出来的
- 过期失效的经验可能导致模式文档看起来比实际更合理/有效
如果用户一开始指定了一篇模式文档，你可以从那里入手以了解其关切点，但在修改模式文档之前，务必先复核其背后的经验文档。
Maintenance Model
对每个候选文档产物，将其分类为以下五种结果之一：
| 处理结果 | 含义 | 默认动作 |
|---|---|---|
| Keep（保留） | 依旧准确且具有实用价值 | 默认不修改文件；在报告中注明已复核且值得信赖 |
| Update（更新） | 核心解决方案仍然正确，但引用/路径等发生了偏离 | 根据确凿证据直接在原文件上进行修改 |
| Consolidate（合并） | 两篇或多篇文档高度重叠但内容均正确 | 将独特内容合并至主文档（Canonical Doc），删除被包含的文档 |
| Replace（替换） | 旧文档会产生误导，但已知有更好的替代方案 | 创建一份可靠的新文档，然后删除旧文档 |
| Delete（删除） | 不再有用、不再适用或不再独立存在 | 删除该文件 —— git 历史记录保留了它，以便日后有需要时恢复 |
Core Rules
- 用证据辅助决策。 下文列出的信号是输入参考，而非机械化的计分卡。请运用工程判断力来决定文档是否依然值得信赖。
- 优先选择不写入的 Keep。 不要为了留下一条“已复核”的痕迹而专门去修改文档。
- 让文档向现实看齐，而不是反过来。 当当前代码与经验文档不一致时，请更新文档以反映当前代码。本 Skill 的职责是保证文档准确性，而不是做 Code Review —— 不要去问用户代码变更究竟是“有意的”还是“退化（regression）”。如果代码改了，文档就该匹配。如果用户认为代码有错，那是本工作流之外的独立问题。
- 果断决策，减少提问。 当证据十分明确时（如文件重命名、类移动、引用失效），直接应用更新。在交互模式下，仅当正确的做法确实存在歧义时才询问用户。在非交互模式下，将模棱两可的情况标记为 stale 而不是提问。我们的目标是在人工把关关键判断的前提下实现自动化维护，而不是每发现一个点就问一次。
- 避免无价值的无用修改（churn）。 不要仅仅为了修复错别字、润色文案或做不影响准确性与易用性的表面修饰而去编辑文档。
- 仅在存在有价值且有证据支撑的偏离时使用 Update。 路径、模块名称、相关链接、分类元数据、代码片段以及明显过时的表述，只要修复它们能显著提升准确性，都在允许修改之列。归错类也是一种偏离：当文档的所在目录与其 Frontmatter 中的 category 不一致，或者其内容明确属于另一个现有的分类时，请按 Update 流程中的迁移说明重新安放文件。
