compound-docs

compound-docs

Process

Single-file architecture -- one markdown file per problem in its symptom category directory (e.g., docs/solutions/performance-issues/n-plus-one-briefs.md), with YAML frontmatter for metadata.

Follow the 7-step documentation capture process. For full details, see documentation-process.md.

1. Detect confirmation -- Auto-invoke after "that worked", "it's fixed", etc. Skip trivial fixes.
2. Gather context -- Extract module, symptom, investigation attempts, root cause, solution, prevention. BLOCK if critical context missing.
3. Check existing docs -- Search docs/solutions/ for similar issues. If found, offer: new doc with cross-reference, update existing, or other.
4. Generate filename -- Format: [sanitized-symptom]-[module]-[YYYYMMDD].md
5. Validate YAML -- Save the draft to a temporary Markdown file, then run validate-frontmatter.sh against it. The validator requires Python 3 and PyYAML; report a missing dependency rather than claiming validation. If invalid, fix the frontmatter and re-run until it passes.
6. Create documentation -- Write file to docs/solutions/[category]/[filename].md using resolution-template.md.
7. Cross-reference -- Link related issues. Detect critical patterns (3+ similar issues).

Capture gate (step 1): capture only if, without this doc, a future engineer reading the final code, tests, comments, CLAUDE.md/AGENTS.md, and existing docs or skills would still repeat the mistake or redo the investigation. Skip when any of those already carries the lesson.

Decision Menu

After successful documentation, present and WAIT for user response:

Solution documented

File created:
- docs/solutions/[category]/[filename].md

What's next?
1. Continue workflow (recommended)
2. Add to Required Reading - Promote to critical patterns
3. Link related issues - Connect to similar problems
4. Add to existing skill - Add to a learning skill
5. Create new skill - Extract into new learning skill
6. View documentation - See what was captured
7. Other