compound-docs

name	compound-docs
user-invocable	true
description	Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
allowed-tools	["Read","Write","Bash","Grep"]
model	inherit
preconditions	["Problem has been solved (not in-progress)","Solution has been verified working"]

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