---
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

1. If `$ARGUMENTS` provided, use as description
2. If no args, check scratchpad DEAD-END/DECISION entries,
   `git diff`, `.claude/plans/{slug}/progress.md` for recent completions
3. 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

1. **Continue** (default)
2. **Promote to Iron Law check** — Add to iron-law-judge
3. **Update skill reference** — Add to relevant skill
4. **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

1. **YAML frontmatter validates or STOP**
2. **Symptoms must be specific** — not "it broke"
3. **Root cause is WHY, not WHAT**
4. **One problem per file**
5. **NEVER document a fix before verifying it works** — run `mix compile && mix test` first; unverified solutions poison the knowledge base

## Integration with Workflow

```text
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