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-docs3user-invocable: true4description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup5allowed-tools:6 - Read7 - Write8 - Bash9 - Grep10model: inherit11preconditions:12 - Problem has been solved (not in-progress)13 - Solution has been verified working14---1516# compound-docs Skill1718**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).1920**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.2122## Process Overview2324Execute the 7-step capture process. Read `capture-process.md` for full step details.2526| Step | What | Blocking? |27|------|------|-----------|28| 1 | Detect confirmation ("that worked", "it's fixed", `/doc-fix`) | Yes |29| 2 | Gather context (module, symptom, root cause, solution) | Yes -- ask user if missing |30| 3 | Check existing docs for similar issues | No |31| 4 | Generate filename (`[symptom]-[module]-[YYYYMMDD].md`) | Yes |32| 5 | Validate YAML schema against `yaml-schema.md` enums | **BLOCKING GATE** |33| 6 | Create documentation file in category directory | Yes |34| 7 | Cross-reference and critical pattern detection | No |3536**After capture**: Present decision menu from `decision-menu.md` and WAIT for user response.3738## Reference Files3940Read the relevant reference file for each phase. All files are in `~/.claude/skills/compound-docs/references/`.4142| File | Content |43|------|---------|44| `capture-process.md` | Full 7-step process with examples, blocking requirements, and bash commands |45| `yaml-schema.md` | YAML frontmatter schema -- required fields, enum values, validation rules, category mapping |46| `decision-menu.md` | Post-capture decision menu (7 options), integration points, skill handoff rules |47| `quality-guidelines.md` | Success criteria, error handling, execution guidelines, quality checklist, example scenario |4849## Key Rules5051**MUST do:**52- Validate YAML frontmatter (BLOCK if invalid per Step 5)53- Extract exact error messages from conversation54- Include code examples in solution section55- Create directories before writing files (`mkdir -p`)56- Ask user and WAIT if critical context missing5758**MUST NOT do:**59- Skip YAML validation (blocking gate)60- Use vague descriptions (not searchable)61- Omit code examples or cross-references62- Auto-promote to Required Reading (user decides)6364## Triggers6566- `/compound-docs` or `/doc-fix` command67- Auto-invoke after: "that worked", "it's fixed", "working now", "problem solved", "that did it"68- Only for non-trivial problems (multiple attempts, tricky debugging, non-obvious solution)6970## Integration7172- **Invoked by**: /compound command, manual invocation, confirmation phrase detection73- **Invokes**: None (terminal skill)74- **Context**: All needed context should be in conversation history before invocation
barkleesanders