compound-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compound Documentation Skill

Manages solution documentation in

docs/solutions/

for knowledge persistence across sessions.

管理

docs/solutions/

目录下的解决方案文档，以实现跨会话的知识留存。

Overview

概述

When you solve a problem, document it so the solution can be found and reused later.

当你解决一个问题时，请将其记录下来，以便日后可以查找和复用该解决方案。

What do you want to do?

你想要执行什么操作？

Document a solution → Use
```
/compound
```
workflow
Find existing solutions → See "Searching Solutions" below
Promote to pattern → See "Pattern Promotion" below
Validate schema → See "YAML Validation" below

记录解决方案 → 使用
```
/compound
```
工作流
查找现有解决方案 → 参见下方“搜索解决方案”
升级为模式 → 参见下方“模式升级”
验证Schema → 参见下方“YAML验证”

Instrumentation

使用记录

bash

undefined

bash

undefined

Log usage when using this skill

使用该Skill时记录使用情况

./scripts/log-skill.sh "compound-docs" "manual" "$$"

undefined

./scripts/log-skill.sh "compound-docs" "manual" "$$"

undefined

Searching Solutions

搜索解决方案

bash

undefined

bash

undefined

Search by keyword

按关键词搜索

grep -r "keyword" docs/solutions/

Search by tag

按标签搜索

grep -l "tags:.performance" docs/solutions/**/.md

Search by problem type

按问题类型搜索

ls docs/solutions/performance-issues/

undefined

ls docs/solutions/performance-issues/

undefined

Pattern Promotion

模式升级

When an issue occurs 3+ times:

Search for similar solutions:
bash
```
grep -r "similar terms" docs/solutions/
```

Add to critical patterns:

bash

# Edit docs/solutions/patterns/critical-patterns.md

Format:

markdown

### Pattern #{N}: {Name}

**Problem:** {What goes wrong}

**❌ WRONG:**
```code
{incorrect}

✅ CORRECT:

code

{correct}

undefined

当某个问题出现3次及以上时：

搜索类似解决方案：
bash
```
grep -r "similar terms" docs/solutions/
```

添加到关键模式：

bash

# 编辑 docs/solutions/patterns/critical-patterns.md

格式要求：

markdown

### Pattern #{N}: {Name}

**问题：** {出现的问题描述}

**❌ 错误示例：**
```code
{错误代码}

✅ 正确示例：

code

{正确代码}

undefined

YAML Validation

YAML验证

All solutions must have valid frontmatter:

yaml

---
date: "YYYY-MM-DD"
problem_type: "{from schema.yaml}"
severity: "critical|high|medium|low"
symptoms:
  - "symptom 1"
root_cause: "{from schema.yaml}"
tags:
  - tag1
---

See

docs/solutions/schema.yaml

for valid enum values.

所有解决方案必须包含有效的前置元数据：

yaml

---
date: "YYYY-MM-DD"
problem_type: "{from schema.yaml}"
severity: "critical|high|medium|low"
symptoms:
  - "symptom 1"
root_cause: "{from schema.yaml}"
tags:
  - tag1
---

请查看

docs/solutions/schema.yaml

获取有效的枚举值。

Documenting Failures & Learnings

记录失败与经验总结

When documenting solutions, capture the full journey:

记录解决方案时，请完整记录整个排查过程：

What to Include

需要包含的内容

✅ Failed attempts with explanations
✅ Incorrect assumptions and corrections
✅ Key insights from mistakes
✅ Course corrections and why
✅ Time investment (helps prioritize future similar issues)

✅ 失败的尝试及原因说明
✅ 错误的假设及修正
✅ 从错误中获得的关键洞见
✅ 调整的方向及原因
✅ 投入的时间（有助于未来对类似问题进行优先级排序）

Example Pattern

示例模式

markdown

undefined

markdown

undefined

Investigation Steps

排查步骤

Attempt	Hypothesis	Result
1. Check API logs	API might be timing out	❌ No timeouts found
2. Review database queries	N+1 query suspected	❌ Queries were optimized
3. Check cache invalidation	Cache might be stale	✅ Found cache not clearing

尝试次数	假设	结果
1. 检查API日志	API可能超时	❌ 未发现超时
2. 审查数据库查询	怀疑存在N+1查询	❌ 查询已优化
3. 检查缓存失效逻辑	缓存可能已过期	✅ 发现缓存未清理

Lessons Learned

经验总结

Mistakes Made

犯过的错误

Assumption: Assumed the API was the bottleneck
- Why wrong: Didn't check cache layer first
- Correction: Should always check cache before API

假设： 认为API是瓶颈
- 错误原因： 没有先检查缓存层
- 修正： 应先检查缓存再排查API

Key Breakthrough

关键突破

Insight: Realized cache invalidation logic was only running on UPDATE, not DELETE
- Impact: Led directly to the solution


> [!TIP]
> **Document the journey, not just the destination.** Future readers learn from understanding WHY failed approaches didn't work.

洞见： 发现缓存失效逻辑仅在UPDATE时运行，DELETE时不运行
- 影响： 直接指向了解决方案


> [!提示]
> **记录完整过程，而不仅仅是最终结果。** 后续读者可以通过了解失败方案的原因学到更多。

References

参考资料

Schema:
```
docs/solutions/schema.yaml
```

Template:

docs/solutions/templates/solution-template.md

Patterns:

docs/solutions/patterns/critical-patterns.md

Schema文件：
```
docs/solutions/schema.yaml
```

模板文件：

docs/solutions/templates/solution-template.md

模式文件：

docs/solutions/patterns/critical-patterns.md