compound-docs

$npx mdskill add oliver-kriska/claude-elixir-phoenix/compound-docs

Searches for existing Elixir/Phoenix/Ecto solutions before debugging

  • Identifies and applies previously solved issues to current problems
  • Utilizes YAML frontmatter metadata for quick lookup of solutions
  • Decides which solution to apply based on problem type and symptoms
  • Delivers the applied solution directly to the user or agent

SKILL.md

.github/skills/compound-docsView on GitHub ↗
---
name: compound-docs
description: "Searchable Elixir/Phoenix/Ecto solution documentation system with YAML frontmatter. Builds institutional knowledge from solved problems. Use when consulting past solutions before investigating new issues."
effort: low
user-invocable: false
---

# 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

1. **ALWAYS search solutions before investigating** — Check
   `.claude/solutions/` for existing fixes before debugging
2. **YAML frontmatter is MANDATORY** — Every solution needs
   validated metadata per `${CLAUDE_SKILL_DIR}/references/schema.md`
3. **One problem per file** — Never combine multiple solutions
4. **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:compound` creates solution docs here
- `/phx:investigate` searches here before debugging
- `/phx:plan` consults for known risks
- `learn-from-fix` feeds into this system

## References

- `${CLAUDE_SKILL_DIR}/references/schema.md` — YAML frontmatter validation schema
- `${CLAUDE_SKILL_DIR}/references/resolution-template.md` — Full solution template

More from oliver-kriska/claude-elixir-phoenix

SkillDescription
ash-frameworkAsh Framework — resources, actions, policies, aggregates, calculations, AshPhoenix.Form, LiveView, migrations. Use when generating resources via mix ash.codegen, editing changes, checks, types, validations, or domain code interfaces.
catchupSummarize and review what changed while you were away. Use after a weekend, vacation, or flight to check missed PRs, git commits, Linear tickets, and meetings — one prioritized brief, not a firehose.
cc-changelog|
codex-abRun an A/B codex review experiment — holistic codex review vs 3 focused dimension passes (security, ecto, liveview) on the branch diff, classify findings, report a panel-value verdict. Use when the branch is fresh, before any codex review runs.
docs-check|
ecto-n1-checkDetect N+1 query anti-patterns specifically — Repo calls inside Enum/for
ecto-patternsEcto patterns — schemas, changesets, queries, migrations, Multi, associations, preloads, upserts. Use when editing Repo calls, Ecto.Query, or schema fields. Skip for Ash.
ecto:constraint-debugDebug Ecto constraint violations - trace triggers, check migrations, find duplicate data. Use when seeing unique_constraint, foreign_key_constraint, or check_constraint errors.
ecto:n1-checkDetect N+1 query anti-patterns specifically — Repo calls inside Enum/for loops, missing preloads on associations. Use when N+1 is explicitly suspected, NOT for unrelated Ecto questions or wider database performance.
elixir-idiomsOTP/BEAM patterns and Elixir idioms — GenServer, Supervisor, Task, Registry, pattern matching, with chains, pipes. Use when designing processes or debugging BEAM issues.