发现已验证且可复用的洞察时，用结构化 Markdown…

适用于开发、学习、项目、工具等工作中出现可复用且已验证的洞察时，及时记录为可搜索知识库并维护关联。

适用场景

解决思路

1. 在对话中自动检测触发语句，如“这成功了”“这个方法不错”“下次也这样”“记下来”“这个格式管用”“这个有效”“这样做就成了”“得记住”；也可用 `/compound` 命令手动触发。
2. 只捕捉非平凡且具复用价值的洞察：可重复模式、可迁移到其他情境的教训、试错后发现的方法、实战验证过的做法、带来结构性改进的发现。
3. 跳过不符合条件的内容：仅适用于当前情境的一次性方法、单纯事实记录（数值、日期等）、已文档化内容的重复、尚未验证的假设。
4. 从对话历史收集必填上下文：domain（work/learning/project/tool/personal）、insight_type（参照 schema.yaml enum）、component（参照 schema.yaml enum）、context（1-3 句说明出现情境）、key_learning（用一句可泛化的话表达核心教训）、impact（critical/high/medium/low）、tags（小写、连字符分隔的搜索关键词）。
5. 额外收集：背景（正在进行的项目/活动）、尝试过但无效的方法、实际有效的方法、有效的原因、可复现条件。
6. 若 domain、insight_type 或核心洞察不清晰，向用户提问并等待回应：询问属于哪个 domain、insight_type 是什么、核心教训一句话如何总结；必须得到回应后继续。
7. 在 `knowledge/` 中搜索相似洞察：按 domain、tags、insight_type 并行执行 Grep，例如 `Grep pattern="domain: [domain]" path=knowledge/ output_mode=files_with_matches`、`Grep pattern="tags:.*[keyword]" path=knowledge/ output_mode=files_with_matches -i=true`、`Grep pattern="insight_type: [type]" path=knowledge/ output_mode=files_with_matches`。
8. 发现相似文档时，向用户展示选项并等待选择：1 新建文档并添加交叉引用（推荐）；2 更新现有文档（同一洞察的补充）；3 其他。根据选择执行。
9. 没有相似文档时，直接进入文件名生成步骤。
10. 生成文件名：格式为 `YYYYMMDD-[sanitized-insight-slug].md`。
11. 执行文件名清理：全部小写；空格替换为连字符；移除特殊字符（连字符除外）；截断到 80 字符以下。示例：`20260304-claude-code-skill-structure.md`、`20260304-mcp-server-debugging-pattern.md`、`20260304-prompt-iteration-framework.md`。
12. 执行 YAML 验证阻塞门：基于 `schema.yaml` 验证所有必填字段，未全部通过前禁止写文档。
13. 验证字段：`domain` 必须是 schema.yaml enum 值之一；`date` 为 YYYY-MM-DD；`insight_type` 必须是 schema.yaml enum 值之一；`component` 必须是该 domain 在 `domain_component_mapping` 中映射的 enum 值之一；`context` 20-300 字且具体描述情境；`key_learning` 10-200 字且可泛化；`impact` 为 critical/high/medium/low；`tags` 1-8 个且小写连字符分隔。
14. YAML 验证失败时显示具体错误并阻止进入文档编写步骤，要求用户提供修正值；示例错误包括 domain 不在允许值、component 不适用于该 domain、tags 含大写。
15. 决定类别目录：使用 `schema.yaml` 的 `category_mapping` 将 `insight_type` 映射到存储路径。
16. 编写文档前，用 `mkdir -p "${CATEGORY_DIR}"` 创建类别目录（如不存在）。
17. 基于 `assets/resolution-template.md` 编写文档：设置 INSIGHT_TYPE、CATEGORY_DIR、FILENAME、DOC_PATH，将步骤 2 收集的上下文与步骤 5 验证通过的 YAML frontmatter 写入 `${CATEGORY_DIR}${FILENAME}`。
18. 文档保存位置为 `knowledge/[category]/[filename].md`，每个洞察一个文件，通过 enum 验证保证分类一致。
19. 若发现相似文档，在现有文档中添加 Related 部分，并在新文档中添加指向现有文档的链接。
20. 检测模式候选：同一类别中相似洞察达到 3 个或以上时，提示用户可综合到 `patterns/` 文档，并询问是否执行。
21. 判断 Critical Pattern 升迁候选但不自动升迁：impact 为 critical、可跨多个 domain 应用、必须记住的内容；由用户决定。
22. 对 Critical Pattern 升迁候选，在 Decision Menu 的“2. 添加到关键模式”选项旁添加注释：“这个洞察值得考虑升迁为关键模式。”
23. 文档化成功后显示 Decision Menu 并等待用户：展示创建的文件路径，列出选项 1 继续（推荐）、2 添加到 critical-patterns.md、3 连接相关文档、4 添加到现有技能、5 查看文档。
24. 处理选项 1：返回当前工作/工作流，文档化完成。
25. 处理选项 2：当模式反复应用、绝不可忘或反直觉但必需时，从文档提取模式，按 `assets/critical-pattern-template.md` 结构化，追加到 `knowledge/patterns/critical-patterns.md` 并保持顺序编号，给该文档添加交叉引用，确认“已添加到关键模式”。
26. 处理选项 3：询问要连接哪个文档（文件名或主题描述），在 `knowledge/` 中搜索目标文档，添加双向交叉引用，确认“交叉引用已添加”。
27. 处理选项 4：询问要添加到哪个技能，向 `.claude/skills/[skill-name]/` 的合适文件添加链接和说明，确认“已添加到 [skill-name] 技能”。
28. 处理选项 5：显示生成文档内容，然后再次呈现 Decision Menu。
29. 集成调用：通过 `/compound` 命令（主要接口）、对话中确认语句自动检测、工作流完成后手动调用。
30. 作为 terminal 技能运行：不向其他技能委派任务。
31. 调用前确保对话历史中有足够上下文供提取。
32. 满足成功标准：YAML frontmatter 验证通过（所有必填字段、正确格式、有效 enum 值）；文件创建于 `knowledge/[category]/[filename].md`；domain-component 映射与 schema.yaml 一致；Context、What Worked、Why This Works 部分具体；发现相似文档时已添加交叉引用；向用户展示 Decision Menu 并确认动作。
33. 错误处理：上下文不足时向用户询问缺失信息，获得必填信息前不继续。
34. 错误处理：YAML 验证失败时显示具体错误项，用修正值重试，直到通过。
35. 错误处理：相似洞察模糊时显示所有候选，让用户选择新建文档、更新现有文档或额外连接。
36. 错误处理：类别映射不确定时建议最接近的类别，经用户确认后继续。
37. 执行必须项：验证 YAML frontmatter（Step 5 validation gate 为 blocking）；检查 domain-component 映射有效性；写文件前用 `mkdir -p` 创建目录；上下文缺失时询问并等待；`key_learning` 要泛化到其他情境。
38. 执行禁止项：不跳过 YAML 验证；不用模糊描述导致无法搜索；不记录假设或未验证内容；不自动升迁 critical pattern，必须用户决定。

适用边界 · 注意事项

• 不要用于尚未验证的假设或猜测；只记录已确认的学习。
• 不要用于仅当前情境有效的一次性方法、单纯事实记录（数值/日期等）、已文档化内容的重复。
• 没有复用价值或无需长期检索的内容不要用此流程。