| name | phx-compound |
| description | Capture solved problems as searchable solution docs. Use after fixing bugs, when "that worked", or after successful phx-review or phx-investigate. |
Compound — Capture Solutions as Knowledge
After fixing a problem, capture the solution as searchable
institutional documentation.
Usage
phx-compound Fixed N+1 query in user listing
phx-compound Resolved LiveView timeout in dashboard
phx-compound # Auto-detects from recent session context
Philosophy
Each unit of engineering work should make subsequent units
easier — not harder.
Workflow
Step 1: Detect Context
- If
$ARGUMENTS provided, use as description
- If no args, check scratchpad DEAD-END/DECISION entries,
git diff, .claude/plans/{slug}/progress.md for recent completions
- If unclear, ask: "What problem did you just solve?"
Only document non-trivial problems that required investigation.
Step 2: Search Existing Solutions
Create .claude/solutions/ directory if it doesn't exist (run mkdir -p .claude/solutions).
Then search .claude/solutions/ for relevant keywords using Grep.
If found: Create new (different root cause), Update
existing (same root cause, new symptom), or Skip.
Step 3: Gather Details and Create Solution
Extract from session context: module, symptoms, investigation
steps, root cause, solution code, and prevention advice.
Validate frontmatter against ../compound-docs/references/schema.md,
then create file using ../compound-docs/references/resolution-template.md.
Write-blocked fallback: if writing to .claude/solutions/ is denied
by permissions, do NOT silently drop the solution. Output the full
solution doc inline (fenced markdown the user can paste), then suggest
phx-permissions to allow .claude/solutions/ writes for next time.
Step 4: Decision Menu
- Continue (default)
- Promote to Iron Law check — Add to iron-law-judge
- Update skill reference — Add to relevant skill
- Update CLAUDE.md — Add prevention rule
Auto-Trigger Phrases
When user says "that worked", "it's fixed", "problem solved",
"the fix was" — suggest phx-compound.
Supply-chain finding auto-feed (Phase 3)
When phx-deps-audit produces a BLOCK-severity finding that the
user investigates and confirms is a real malicious pattern (not a
false positive), suggest:
Caught a high-severity finding in <pkg>@<version>. Run
phx-compound to capture this for future audits?
If accepted, the resulting solution doc goes to
.claude/solutions/supply-chain/<pkg>-<cve_or_pattern>.md and
includes the exact rule-id + snippet + diff window that triggered
the finding. This compounds the audit corpus: future runs of
phx-deps-audit grep solutions/supply-chain/ for snippet
matches and pre-elevate severity on known-bad patterns.
Always prompt; never auto-write. Solution docs are durable and
shape future trust calls — the user reviews before committing.
Iron Laws
- YAML frontmatter validates or STOP
- Symptoms must be specific — not "it broke"
- Root cause is WHY, not WHAT
- One problem per file
- NEVER document a fix before verifying it works — run
mix compile && mix test first; unverified solutions poison the knowledge base
Integration with Workflow
phx-review → Complete → phx-compound ← YOU ARE HERE
│
.claude/solutions/{category}/{fix}.md
│
phx-investigate and phx-plan search here
References
references/compound-workflow.md — Detailed step-by-step- See also:
compound-docs skill for schema and templates
