# Compound Docs

> Capture solved problems as categorized documentation with YAML frontmatter for fast lookup

- Skill: `barkleesanders/compound-docs` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add barkleesanders/compound-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/barkleesanders/compound-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: barkleesanders (https://skillmd.com/u/barkleesanders)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/barkleesanders/compound-docs

---


# 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