Compound Docs — Institutional Knowledge Base
Searchable, categorized solution documentation that makes each debugging session easier than the last.
Directory Structure
.claude/solutions/ ├── ecto-issues/ ├── liveview-issues/ ├── oban-issues/ ├── otp-issues/ ├── security-issues/ ├── testing-issues/ ├── phoenix-issues/ ├── deployment-issues/ ├── performance-issues/ └── build-issues/
Iron Laws
- ALWAYS search solutions before investigating — Check
.claude/solutions/for existing fixes before debugging - YAML frontmatter is MANDATORY — Every solution needs
validated metadata per
${CLAUDE_SKILL_DIR}/references/schema.md - One problem per file — Never combine multiple solutions
- Include prevention — Every solution documents how to prevent recurrence
Solution File Format
markdown--- module: "Accounts" date: "2025-12-01" problem_type: runtime_error component: ecto_schema symptoms: - "Ecto.Association.NotLoaded on user.posts" root_cause: missing_preload severity: medium tags: [preload, association, n-plus-one] --- # Association NotLoaded on User Posts ## Symptoms Ecto.Association.NotLoaded raised when accessing user.posts in UserListLive after filtering. ## Root Cause Query in Accounts context missing preload for :posts. ## Solution Added `Repo.preload(:posts)` to `list_users/1`. ## Prevention Use n1-check skill before shipping list views.
Searching Solutions
Use Grep to search .claude/solutions/ by symptom (e.g., NotLoaded), by tag (e.g., tags:.*preload), or by component (e.g., component: ecto).
Integration
/phx:compoundcreates solution docs here/phx:investigatesearches here before debugging/phx:planconsults for known riskslearn-from-fixfeeds into this system
References
${CLAUDE_SKILL_DIR}/references/schema.md— YAML frontmatter validation schema${CLAUDE_SKILL_DIR}/references/resolution-template.md— Full solution template

