compound-docs Skill
Purpose: Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).
Organization: Single-file architecture -- each problem documented as one markdown file in its symptom category directory (e.g., docs/solutions/performance-issues/n-plus-one-briefs.md). Files use YAML frontmatter for metadata and searchability.
Process Overview
Execute the 7-step capture process. Read capture-process.md for full step details.
| Step |
What |
Blocking? |
| 1 |
Detect confirmation ("that worked", "it's fixed", /doc-fix) |
Yes |
| 2 |
Gather context (module, symptom, root cause, solution) |
Yes -- ask user if missing |
| 3 |
Check existing docs for similar issues |
No |
| 4 |
Generate filename ([symptom]-[module]-[YYYYMMDD].md) |
Yes |
| 5 |
Validate YAML schema against yaml-schema.md enums |
BLOCKING GATE |
| 6 |
Create documentation file in category directory |
Yes |
| 7 |
Cross-reference and critical pattern detection |
No |
After capture: Present decision menu from decision-menu.md and WAIT for user response.
Reference Files
Read the relevant reference file for each phase. All files are in ~/.claude/skills/compound-docs/references/.
| File |
Content |
capture-process.md |
Full 7-step process with examples, blocking requirements, and bash commands |
yaml-schema.md |
YAML frontmatter schema -- required fields, enum values, validation rules, category mapping |
decision-menu.md |
Post-capture decision menu (7 options), integration points, skill handoff rules |
quality-guidelines.md |
Success criteria, error handling, execution guidelines, quality checklist, example scenario |
Key Rules
MUST do:
- Validate YAML frontmatter (BLOCK if invalid per Step 5)
- Extract exact error messages from conversation
- Include code examples in solution section
- Create directories before writing files (
mkdir -p)
- Ask user and WAIT if critical context missing
MUST NOT do:
- Skip YAML validation (blocking gate)
- Use vague descriptions (not searchable)
- Omit code examples or cross-references
- Auto-promote to Required Reading (user decides)
Triggers
/compound-docs or /doc-fix command- Auto-invoke after: "that worked", "it's fixed", "working now", "problem solved", "that did it"
- Only for non-trivial problems (multiple attempts, tricky debugging, non-obvious solution)
Integration
- Invoked by: /compound command, manual invocation, confirmation phrase detection
- Invokes: None (terminal skill)
- Context: All needed context should be in conversation history before invocation
1---2name: compound-docs3description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup4---56# compound-docs Skill78**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).910**Organization:** Single-file architecture -- each problem documented as one markdown file in its symptom category directory (e.g., `docs/solutions/performance-issues/n-plus-one-briefs.md`). Files use YAML frontmatter for metadata and searchability.1112## Process Overview1314Execute the 7-step capture process. Read `capture-process.md` for full step details.1516| Step | What | Blocking? |17|------|------|-----------|18| 1 | Detect confirmation ("that worked", "it's fixed", `/doc-fix`) | Yes |19| 2 | Gather context (module, symptom, root cause, solution) | Yes -- ask user if missing |20| 3 | Check existing docs for similar issues | No |21| 4 | Generate filename (`[symptom]-[module]-[YYYYMMDD].md`) | Yes |22| 5 | Validate YAML schema against `yaml-schema.md` enums | **BLOCKING GATE** |23| 6 | Create documentation file in category directory | Yes |24| 7 | Cross-reference and critical pattern detection | No |2526**After capture**: Present decision menu from `decision-menu.md` and WAIT for user response.2728## Reference Files2930Read the relevant reference file for each phase. All files are in `~/.claude/skills/compound-docs/references/`.3132| File | Content |33|------|---------|34| `capture-process.md` | Full 7-step process with examples, blocking requirements, and bash commands |35| `yaml-schema.md` | YAML frontmatter schema -- required fields, enum values, validation rules, category mapping |36| `decision-menu.md` | Post-capture decision menu (7 options), integration points, skill handoff rules |37| `quality-guidelines.md` | Success criteria, error handling, execution guidelines, quality checklist, example scenario |3839## Key Rules4041**MUST do:**42- Validate YAML frontmatter (BLOCK if invalid per Step 5)43- Extract exact error messages from conversation44- Include code examples in solution section45- Create directories before writing files (`mkdir -p`)46- Ask user and WAIT if critical context missing4748**MUST NOT do:**49- Skip YAML validation (blocking gate)50- Use vague descriptions (not searchable)51- Omit code examples or cross-references52- Auto-promote to Required Reading (user decides)5354## Triggers5556- `/compound-docs` or `/doc-fix` command57- Auto-invoke after: "that worked", "it's fixed", "working now", "problem solved", "that did it"58- Only for non-trivial problems (multiple attempts, tricky debugging, non-obvious solution)5960## Integration6162- **Invoked by**: /compound command, manual invocation, confirmation phrase detection63- **Invokes**: None (terminal skill)64- **Context**: All needed context should be in conversation history before invocation
barkleesanders