compound-docs

Process

docs/solutions/performance-issues/n-plus-one-briefs.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 -- Run validate-frontmatter.sh against the file. 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).

Decision Menu

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

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

• Stale-learning review (

  /ia-compound-refresh

  in Claude Code) -- reviews

  docs/solutions/

  for entries that have aged out