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.
- Detect confirmation -- Auto-invoke after "that worked", "it's fixed", etc. Skip trivial fixes.
- Gather context -- Extract module, symptom, investigation attempts, root cause, solution, prevention. BLOCK if critical context missing.
- Check existing docs -- Search
docs/solutions/for similar issues. If found, offer: new doc with cross-reference, update existing, or other. - Generate filename -- Format:
[sanitized-symptom]-[module]-[YYYYMMDD].md - Validate YAML -- Run validate-frontmatter.sh against the file. If invalid, fix the frontmatter and re-run until it passes.
- Create documentation -- Write file to
docs/solutions/[category]/[filename].mdusing resolution-template.md. - Cross-reference -- Link related issues. Detect critical patterns (3+ similar issues).
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. OtherFor detailed response handling, see documentation-process.md.
Success Criteria
- YAML frontmatter validated (all required fields, correct formats)
- File created in
docs/solutions/[category]/[filename].md - Enum values match schema exactly
- Code examples included in solution section
- Cross-references added if related issues found
- User presented with decision menu and action confirmed
References
- documentation-process.md - Full 7-step process with validation gates
- yaml-schema.md - YAML frontmatter schema and enum values
- quality-guidelines.md - Quality standards, execution rules, error handling
- example-scenario.md - Complete walkthrough of documenting an N+1 query fix
- resolution-template.md - Template for documentation files
- critical-pattern-template.md - Template for critical pattern entries
- validate-frontmatter.sh - Validate YAML frontmatter against schema
Integration
/ia-compound-refreshcommand -- reviewsdocs/solutions/for stale learnings