compound-docs

compound-docs 技能

用途： 自动记录已解决的问题，按类别组织（问题类型通过枚举验证），以构建可搜索的机构知识库。

概述

此技能会在问题确认后立即记录解决方案，创建结构化文档，作为未来会话可搜索的知识库。

组织方式： 单文件架构——每个问题都作为一个 Markdown 文件记录在对应的症状类别目录中（例如，docs/solutions/performance-issues/n-plus-one-briefs.md）。文件使用 YAML frontmatter 存储元数据，以便搜索。

---

<critical_sequence name="documentation-capture" enforce_order="strict">

7 步流程

### 第 1 步：检测确认

在出现以下短语后自动调用：

• “that worked”
• “it's fixed”
• “working now”
• “problem solved”
• “that did it”

或手动调用： /doc-fix 命令

仅限非简单问题：

• 需要多次尝试排查
• 调试棘手且耗时
• 解决方案不明显
• 未来会话能从中受益

以下情况跳过记录：

• 简单的拼写错误
• 明显的语法错误
• 立即修正的琐碎问题

### 第 2 步：收集上下文

从对话历史中提取：

必需信息：

• 模块名称：出现问题的模块或组件
• 症状：可观察到的错误或行为（错误消息原文）
• 排查尝试：哪些方法无效，以及原因
• 根本原因：对实际问题的技术说明
• 解决方案：修复问题的方法（代码或配置变更）
• 预防措施：如何避免问题再次发生

环境详情：

• Rails 版本
• 阶段（0-6 或实施后）
• 操作系统版本
• 文件/行号引用

阻塞要求： 如果缺少关键上下文（模块名称、确切错误、阶段或解决步骤），请询问用户，并在继续执行第 3 步之前等待回复：

I need a few details to document this properly:

1. Which module had this issue? [ModuleName]
2. What was the exact error message or symptom?
3. What stage were you in? (0-6 or post-implementation)

[Continue after user provides details]

### 第 3 步：检查现有文档

在 docs/solutions/ 中搜索类似问题：

# Search by error message keywords
grep -r "exact error phrase" docs/solutions/

# Search by symptom category
ls docs/solutions/[category]/

如果找到类似问题：

则提供选项供用户选择：

Found similar issue: docs/solutions/[path]

What's next?
1. Create new doc with cross-reference (recommended)
2. Update existing doc (only if same root cause)
3. Other

Choose (1-3): _

等待用户回复，然后执行所选操作。

否则（未找到类似问题）：

直接进入第 4 步（无需与用户交互）。

### 第 4 步：生成文件名

格式：[sanitized-symptom]-[module]-[YYYYMMDD].md

规范化规则：

• 转为小写
• 用连字符替换空格
• 删除除连字符外的特殊字符
• 截断至合理长度（< 80 个字符）

示例：

• missing-include-BriefSystem-20251110.md
• parameter-not-saving-state-EmailProcessing-20251110.md
• webview-crash-on-resize-Assistant-20251110.md

### 第 5 步：验证 YAML 架构

重要： 所有文档都必须包含经过验证的 YAML frontmatter，并进行枚举验证。

<validation_gate name="yaml-schema" blocking="true">

根据架构进行验证： 加载 schema.yaml，并依据 yaml-schema.md 中定义的枚举值对问题进行分类。确保所有必需字段均已提供，且与允许值完全匹配。

如果验证失败则阻止继续：

❌ YAML validation failed

Errors:
- problem_type: must be one of schema enums, got "compilation_error"
- severity: must be one of [critical, high, medium, low], got "invalid"
- symptoms: must be array with 1-5 items, got string

Please provide corrected values.

门禁执行要求： 在 YAML frontmatter 通过 schema.yaml 中定义的所有验证规则之前，不要继续执行第 6 步（创建文档）。

</validation_gate>

### 步骤 6：创建文档

根据 problem_type 确定类别： 使用 yaml-schema.md（第 49-61 行）中定义的类别映射。

创建文档文件：

PROBLEM_TYPE="[from validated YAML]"
CATEGORY="[mapped from problem_type]"
FILENAME="[generated-filename].md"
DOC_PATH="docs/solutions/${CATEGORY}/${FILENAME}"

# Create directory if needed
mkdir -p "docs/solutions/${CATEGORY}"

# Write documentation using template from assets/resolution-template.md
# (Content populated with Step 2 context and validated YAML frontmatter)

结果：

• 类别目录中只有一个文件
• 枚举验证可确保分类一致

创建文档： 使用第 2 步收集的上下文，以及第 5 步验证过的 YAML frontmatter，填充 assets/resolution-template.md 中的结构。

### 步骤 7：交叉引用与关键模式检测

如果第 3 步发现了类似问题：

更新现有文档：

# Add Related Issues link to similar doc
echo "- See also: [$FILENAME]($REAL_FILE)" >> [similar-doc.md]

更新新文档： 已包含第 6 步中的交叉引用。

如适用，更新模式：

如果这是一个常见模式（3 个或更多类似问题）：

# Add to docs/solutions/patterns/common-solutions.md
cat >> docs/solutions/patterns/common-solutions.md << 'EOF'

## [Pattern Name]

**Common symptom:** [Description]
**Root cause:** [Technical explanation]
**Solution pattern:** [General approach]

**Examples:**
- [Link to doc 1]
- [Link to doc 2]
- [Link to doc 3]
EOF

关键模式检测（可选的主动建议）：

如果此问题具有自动检测指标，表明它可能很关键：

• 严重程度：YAML 中的 critical
• 影响多个模块或基础阶段（阶段 2 或 3）
• 解决方案不明显

则在决策菜单（第 8 步）中添加一条说明：

💡 This might be worth adding to Required Reading (Option 2)

但绝不要自动提升。由用户通过决策菜单（选项 2）决定。

添加关键模式的模板：

当用户选择选项 2（添加到必读内容）时，使用 assets/critical-pattern-template.md 中的模板来组织模式条目。根据 docs/solutions/patterns/critical-patterns.md 中已有的模式，按顺序编号。

</critical_sequence>

---

<decision_gate name="post-documentation" wait_for_user="true">

记录后的决策菜单

成功完成文档记录后，展示选项并等待用户回复：

✓ Solution documented

File created:
- docs/solutions/[category]/[filename].md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

处理回复：

选项 1：继续工作流

• 返回调用此技能/工作流的流程
• 文档已完成

选项 2：添加到必读内容 ⭐ 关键模式的首选路径

用户在以下情况下选择此项：

• 系统在不同模块中多次犯下此错误
• 解决方案不明显，但每次都必须遵循
• 基础要求（Rails、Rails API、线程处理等）

操作：

1. 从文档中提取模式
2. 使用代码示例，按 ❌ 错误与 ✅ 正确的格式编排
3. 添加到 docs/solutions/patterns/critical-patterns.md
4. 添加指向此文档的交叉引用
5. 确认：“✓ 已添加到必读内容。所有子 Agent 在生成代码前都会看到此模式。”

选项 3：关联相关问题

• 提示：“要关联哪个文档？（提供文件名或描述）”
• 在 docs/solutions/ 中搜索该文档
• 在两个文档中都添加交叉引用
• 确认：“✓ 已添加交叉引用”

选项 4：添加到现有技能

用户在记录的解决方案与现有学习技能相关时选择此项：

操作：

1. 提示：“哪个技能？（例如 hotwire-native）”
2. 确定要更新的参考文件（resources.md、patterns.md 或 examples.md）
3. 在相应部分添加链接和简要说明
4. 确认：“✓ 已将内容添加到 [skill-name] 技能的 [file]”

示例：对于 Hotwire Native Tailwind 变体解决方案：

• 在“项目专属资源”下，将其添加到 hotwire-native/references/resources.md
• 将其添加到 hotwire-native/references/examples.md，并附上指向解决方案文档的链接

选项 5：创建新技能

用户在该解决方案标志着一个新学习领域的开始时选择此项：

操作：

1. 提示：“新技能应叫什么？（例如 stripe-billing、email-processing）”
2. 运行 python3 .claude/skills/skill-creator/scripts/init_skill.py [skill-name]
3. 创建初始参考文件，并将此解决方案作为第一个示例
4. 确认：“✓ 已创建新的 [skill-name] 技能，并将此解决方案作为第一个示例”

选项 6：查看文档

• 显示创建的文档
• 再次显示决策菜单

选项 7：其他

• 询问用户想要做什么

</decision_gate>

---

<integration_protocol>

集成点

由以下方式调用：

• /compound 命令（主要接口）
• 在解决方案确认后于对话中手动调用
• 可通过检测“that worked”“it's fixed”等确认短语触发

调用：

• 无（终端技能，不会委派给其他技能）

交接要求： 调用前，对文档编写所需的所有上下文都应已包含在对话历史中。

</integration_protocol>

---

<success_criteria>

成功标准

满足以下所有条件时，文档编写才算成功：

• ✅ YAML frontmatter 已验证（包含所有必填字段，格式正确）
• ✅ 文件已创建于 docs/solutions/[category]/[filename].md
• ✅ 枚举值与 schema.yaml 完全一致
• ✅ 解决方案部分包含代码示例
• ✅ 找到相关问题时已添加交叉引用
• ✅ 已向用户展示决策菜单，并确认操作

</success_criteria>

---

错误处理

上下文缺失：

• 向用户询问缺失的详细信息
• 在获得关键所需信息前不要继续

YAML 验证失败：

• 显示具体错误
• 提供使用修正值重试的选项
• 验证通过前阻止继续

相似问题存在歧义：

• 展示多个匹配项
• 让用户选择：新建文档、更新现有文档，或将其关联为重复项

模块未记录在 modules 文档中：

• 发出警告，但不阻止继续
• 继续编写文档
• 建议：“如果 modules 文档中尚未列出 [Module]，请将其添加进去”

---

执行指南

必须执行：

• 验证 YAML frontmatter（根据第 5 步的验证关卡，验证失败时必须阻止继续）
• 从对话中提取确切的错误消息
• 在解决方案部分加入代码示例
• 写入文件前创建目录（mkdir -p）
• 缺少关键上下文时询问用户并等待回复

不得执行：

• 跳过 YAML 验证（验证关卡具有阻止作用）
• 使用模糊描述（这会导致内容无法搜索）
• 省略代码示例或交叉引用

---

质量指南

优质文档应包含：

• ✅ 确切的错误消息（从输出中复制粘贴）
• ✅ 具体的文件和行号引用
• ✅ 可观察到的症状（你看到的现象，而非解释）
• ✅ 记录失败的尝试（帮助避免走错方向）
• ✅ 技术说明（不仅说明“是什么”，还要说明“为什么”）
• ✅ 代码示例（适用时展示修改前后）
• ✅ 预防建议（如何及早发现）
• ✅ 交叉引用（相关问题）

避免：

• ❌ 模糊描述（“出了点问题”）
• ❌ 缺少技术细节（“修复了代码”）
• ❌ 缺少上下文（哪个版本？哪个文件？）
• ❌ 只贴代码（应解释代码为何有效）
• ❌ 缺少预防建议
• ❌ 缺少交叉引用

---

示例场景

用户：“That worked! The N+1 query is fixed.”

技能激活：

1. 检测确认：“That worked!”会触发自动调用
2. 收集上下文：
   • 模块：Brief System
   • 症状：Brief 生成耗时超过 5 秒；加载电子邮件会话时出现 N+1 查询
   • 失败的尝试：添加分页（没有帮助）、检查后台任务性能
   • 解决方案：在 Brief 模型上添加 includes(:emails)，以预加载关联数据
   • 根本原因：缺少预加载，导致每个电子邮件会话都单独执行一次数据库查询
3. **检查现有内容：**未找到类似问题
4. 生成文件名：n-plus-one-brief-generation-BriefSystem-20251110.md
5. 验证 YAML：

   module: Brief System
   date: 2025-11-10
   problem_type: performance_issue
   component: rails_model
   symptoms:
     - "N+1 query when loading email threads"
     - "Brief generation taking >5 seconds"
   root_cause: missing_include
   severity: high
   tags: [n-plus-one, eager-loading, performance]
   

   ✅ 有效
6. 创建文档：
   • docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md
7. **添加交叉引用：**无需添加（没有类似问题）

输出：

✓ Solution documented

File created:
- docs/solutions/performance-issues/n-plus-one-brief-generation-BriefSystem-20251110.md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns (critical-patterns.md)
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill (e.g., hotwire-native)
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

---

未来增强

不在第 7 阶段的范围内，但可考虑：

• 按日期范围搜索
• 按严重程度筛选
• 基于标签的搜索界面
• 指标（最常见的问题、解决时间）
• 导出为可共享格式（分享社区知识）
• 导入社区解决方案