用途
compound-docs 用于在问题被解决并确认后，自动将解决方案记录为结构化文档，从而构建可搜索的机构知识库。它按问题类型分类组织，通过枚举校验保证分类一致性，让未来的会话能够快速检索到历史问题及其解法。该技能只记录非琐碎问题，即需要多次调查尝试、调试耗时较长、解决方案非显而易见、或对未来会话有价值的问题。简单的拼写错误、明显的语法错误、以及可立即修正的琐碎修复会被跳过。
主要能力
- 自动触发：在检测到确认短语（如 "that worked"、"it's fixed"、"working now"、"problem solved"、"that did it"）后自动调用，也可通过
/doc-fix命令手动调用。 - 上下文提取：从对话历史中提取模块名称、症状（含准确错误信息）、调查尝试、根因、解决方案、预防措施，以及环境细节（Rails 版本、阶段 0-6 或实现后、操作系统版本、文件/行引用）。
- 相似问题检索：在 docs/solutions/ 中按错误信息关键词或症状分类搜索，若发现相似问题，则给出决策选项（新建并交叉引用、更新已有文档、或其他）。
- 文件命名：格式为 [sanitized-symptom]-[module]-[YYYYMMDD].md，规则包括小写、空格替换为连字符、移除非连字符特殊字符、截断至合理长度（< 80 字符）。
- YAML frontmatter 校验：所有文档必须通过 schema.yaml 的枚举校验，包含必填字段并精确匹配允许值。
- 分类映射：根据 problem_type 按 yaml-schema.md 中定义的映射确定分类目录。
- 文档创建：使用 assets/resolution-template.md 模板填充内容，写入 docs/solutions/${CATEGORY}/${FILENAME}，必要时用 mkdir -p 创建目录。
- 交叉引用与模式提取：为相似文档添加 Related Issues 链接；若某模式出现 3 次以上，则追加到 docs/solutions/patterns/common-solutions.md。
- 关键模式升级：对高影响问题（severity 为 critical、影响多个模块或基础阶段、解决方案非显而易见）可经用户选择加入 Required Reading。
使用方式
7 步流程：
- 通过确认短语自动触发或使用
/doc-fix命令手动触发。 - 从对话历史提取必需信息（模块名、症状、调查尝试、根因、解决方案、预防、环境细节）。若缺少关键上下文（模块名、准确错误、阶段、解决方案步骤），必须先向用户询问并等待回应，再进入第 3 步。
- 在 docs/solutions/ 中搜索相似问题；若找到则呈现决策选项并等待用户选择，否则直接进入第 4 步。
- 生成文件名。
- 校验 YAML frontmatter（阻塞性校验门，校验失败则显示具体错误并等待修正值，未通过不得进入第 6 步）。
- 根据校验后的 problem_type 确定分类并创建文档文件。
- 若发现相似问题则更新交叉引用；若适用则更新 patterns/common-solutions.md。
文档捕获后呈现决策菜单并等待用户回应：1. 继续工作流；2. 加入 Required Reading（提升为关键模式）；3. 关联相关问题；4. 加入已有技能；5. 创建新技能；6. 查看文档；7. 其他。
适用场景
适合需要长期积累排障经验的开发工作流，尤其是问题根因非显而易见、排查过程曲折、且未来会再次遇到的情况。典型示例：N+1 查询导致 Brief 生成耗时超过 5 秒，通过为 Brief 模型添加 includes(:emails) 预加载解决，并记录为性能问题类文档。
限制
- 不是所有问题都记录：简单拼写错误、明显语法错误、可立即修正的琐碎修复会被跳过。
- YAML 校验为阻塞性要求，字段值必须与 schema.yaml 中的枚举完全匹配，否则流程被阻断。
- 缺失关键上下文时必须等待用户提供，无法自动补全。
- 模块不在模块文档中时会警告但不阻断，并建议补充模块文档。
- 关键模式绝不自动提升，必须由用户通过决策菜单选择。
- 未来增强功能（按日期范围搜索、按严重程度过滤、基于标签的搜索界面、指标统计、导出可分享格式、导入社区解决方案）暂未提供。
- 平台、收费与价格信息暂未提供。