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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: barkleesanders
• Source: barkleesanders/claude-code-starter
• License: MIT

Install and usage instructions live in the source repository linked above.