compound-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

compound-docs

Process

流程

Single-file architecture -- one markdown file per problem in its symptom category directory (e.g.,

docs/solutions/performance-issues/n-plus-one-briefs.md

), with YAML frontmatter for metadata.

Follow the 7-step documentation capture process. For full details, see documentation-process.md.

Detect confirmation -- Auto-invoke after "that worked", "it's fixed", etc. Skip trivial fixes.
Gather context -- Extract module, symptom, investigation attempts, root cause, solution, prevention. BLOCK if critical context missing.
Check existing docs -- Search
```
docs/solutions/
```
for similar issues. If found, offer: new doc with cross-reference, update existing, or other.

Generate filename -- Format:

[sanitized-symptom]-[module]-[YYYYMMDD].md

Validate YAML -- Run validate-frontmatter.sh against the file. If invalid, fix the frontmatter and re-run until it passes.
Create documentation -- Write file to
```
docs/solutions/[category]/[filename].md
```
using resolution-template.md.
Cross-reference -- Link related issues. Detect critical patterns (3+ similar issues).

单文件架构——每个问题对应一个Markdown文件，存放在其症状分类目录下（例如：

docs/solutions/performance-issues/n-plus-one-briefs.md

），并使用YAML前置元数据。

遵循7步文档记录流程。详细内容请参考documentation-process.md。

触发确认——当出现“问题解决了”“修复完成”等表述时自动触发。跳过无关紧要的小修复。
收集上下文信息——提取模块、症状、排查尝试、根本原因、解决方案、预防措施。如果关键上下文缺失则暂停。
检查现有文档——在
```
docs/solutions/
```
目录中搜索类似问题。如果找到，提供选项：新建文档并添加交叉引用、更新现有文档，或其他操作。

生成文件名——格式：

[清理后的症状名称]-[模块]-[YYYYMMDD].md

验证YAML前置元数据——对文件运行validate-frontmatter.sh脚本。如果验证不通过，修改前置元数据后重新运行直到通过。
创建文档——使用resolution-template.md模板，将文件写入
```
docs/solutions/[分类]/[文件名].md
```
。
添加交叉引用——关联相关问题。识别关键模式（3个及以上相似问题）。

Decision Menu

操作选择菜单

After successful documentation, present and WAIT for user response:

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
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other

For detailed response handling, see documentation-process.md.

文档创建成功后，展示以下内容并等待用户响应：

解决方案已记录

已创建文件：
- docs/solutions/[分类]/[文件名].md

下一步操作？
1. 继续工作流（推荐）
2. 添加至必学内容——标记为关键模式
3. 关联相关问题——连接至相似问题
4. 添加至现有技能——整合到已有的学习技能中
5. 创建新技能——提炼为新的学习技能
6. 查看文档——查看已记录的内容
7. 其他操作

详细的响应处理规则请参考documentation-process.md。

Success Criteria

成功标准

YAML frontmatter validated (all required fields, correct formats)
File created in
```
docs/solutions/[category]/[filename].md
```
Enum values match schema exactly
Code examples included in solution section
Cross-references added if related issues found
User presented with decision menu and action confirmed

YAML前置元数据验证通过（包含所有必填字段，格式正确）
文件已创建在
```
docs/solutions/[分类]/[文件名].md
```
路径下
枚举值与schema完全匹配
解决方案部分包含代码示例
若找到相关问题则已添加交叉引用
已向用户展示操作选择菜单并确认操作

References

参考资料

documentation-process.md - Full 7-step process with validation gates
yaml-schema.md - YAML frontmatter schema and enum values
quality-guidelines.md - Quality standards, execution rules, error handling
example-scenario.md - Complete walkthrough of documenting an N+1 query fix
resolution-template.md - Template for documentation files
critical-pattern-template.md - Template for critical pattern entries
validate-frontmatter.sh - Validate YAML frontmatter against schema

documentation-process.md - 包含验证节点的完整7步流程
yaml-schema.md - YAML前置元数据的schema及枚举值
quality-guidelines.md - 质量标准、执行规则、错误处理
example-scenario.md - 记录N+1查询修复方案的完整示例流程
resolution-template.md - 文档文件模板
critical-pattern-template.md - 关键模式条目模板
validate-frontmatter.sh - 验证YAML前置元数据是否符合schema的脚本

Integration

集成

Stale-learning review (
```
/ia-compound-refresh
```
in Claude Code) -- reviews
```
docs/solutions/
```
for entries that have aged out

过时知识审核（Claude Code中的
```
/ia-compound-refresh
```
命令）——审核
```
docs/solutions/
```
目录中已过期的条目