# Compound Skill
You are documenting a solved problem so that future sessions can learn from it.
## Core Principle
Every solved problem should make future problems easier. Capture the **problem**, **root cause**, **fix**, and **prevention strategy** in a searchable format.
## Workflow
When the user invokes `/compound` or `/compound <description>`:
### 1. Gather Context
If a description is provided, use it as context. Otherwise, first sync the fresh upstream ref without touching the local `main` branch: `git fetch origin main`. Then:
- `git diff origin/main...HEAD`
- `git log origin/main..HEAD --oneline`
- Spawn the **discovery-thoughts** agent to find the related plan/research
### 2. Check for Existing Solutions
Spawn the **discovery-thoughts** agent to search for related past solutions (by category, tags,
and keywords from the diff). This runs *before* insight extraction so duplication can be judged
before a new file is drafted, not after.
Also check whether this change **supersedes** — not merely duplicates — a specific past solution:
the old file's root cause or prevention strategy is now known to be wrong, incomplete, or replaced
(as opposed to `Duplicate`, where the old file's guidance was correctly reapplied). Note the
candidate path if so; it feeds step 5's supersession step.
### 3. Extract Insight
Spawn the **ops-insight** agent with: the diff summary, commit messages, plan path (or N/A),
branch name, and the related past solutions found in step 2 (path + problem/root-cause/prevention
summary for each).
The agent returns a draft with a `confidence` field: `High`, `Duplicate`, or `Low`.
### 4. Decide Whether to Document
- **High confidence**: Proceed to step 5.
- **Duplicate confidence**: **Skip writing a new file**. If the affected code doesn't already
reference the existing solution, add the WHY-comment link (step 6) pointing at it. Report:
> "Compound: skipped — already covered by `solutions/<category>/<existing-file>.md`."
- **Low confidence**: **Skip silently**. Report:
> "Compound: skipped — changes don't contain a clear, documentable insight."
Trivial changes to always skip:
- Typo fixes, formatting-only changes
- Import reordering, method reordering
- Renames with no logic change
- Comment-only additions
- A routine reapplication of an already-documented pattern with no new failure mode (this is what
`ops-insight`'s `Duplicate` confidence flags — see above)
### 5. Write the Solution Document
Create at: `solutions/<category>/YYYY-MM-DD-HHmm-<description-slug>.md`
Categories: `distribution`, `algorithm`, `correctness`, `special-functions`, `performance`, `testing`, `tooling`
A new solution always gets `status: complete` — never set anything else at write time. Use this
format:
```markdown
---
date: <ISO timestamp>
category: "<category>"
problem: "<one-line problem summary>"
status: complete
related_issue: "<#number or N/A>"
related_plan: "<path or N/A>"
tags: [<relevant keywords>]
---
# Solution: <description>
**Date**: <timestamp>
**Category**: <category>
**Related Issue**: <#number or N/A>
## Problem
<What went wrong — symptoms, not just "file X was changed">
## Root Cause
<Why it happened — the underlying mathematical or implementation issue>
## Fix
<What was done — the approach and reasoning>
## Prevention Strategy
<How to avoid this in the future — patterns to follow, checks to add>
## Related Solutions
- <Link to related past solutions, if any>
## Key Insight
<One sentence capturing the most important takeaway>
```
If step 2 flagged a past solution as **superseded** by this one (its root cause or prevention
strategy is now wrong or incomplete — see step 2), update that older file's frontmatter in place:
set `status: superseded` and add `superseded_by: "solutions/<category>/<this-new-file>.md"`. Leave
the rest of the old file untouched — it stays as an immutable historical record, just no longer the
authoritative guidance for its topic. Stage it alongside the new file in step 7.
### 6. Link in Code
After writing the solution file, insert a reference at the most directly affected code location:
- **Function/class fix** → WHY comment at the changed line:
```js
// See solutions/<category>/YYYY-MM-DD-HHmm-<slug>.md
```
- **Module-wide decision** → reference in the module's top comment
- Use the relative path from the repo root (grep-able)
Stage the code change together with the solution file.
### 7. Commit
```bash
git add solutions/<category>/YYYY-MM-DD-HHmm-<slug>.md <affected-file-if-linked> <superseded-file-if-any>
git commit -m "Solution compounded for #<issue> — <slug>"
```
Do **not** push here — let the caller handle pushing.
### 8. Report
> "Solution documented at:
>
> `solutions/<category>/YYYY-MM-DD-HHmm-<slug>.md`
>
> **Key insight**: <the one-sentence takeaway>"
## Rules
### DO:
- Let ops-insight decide whether the work is worth documenting
- Focus on the WHY (root cause) and the LESSON (prevention)
- Use specific, searchable tags
- Reference related past solutions when they exist
### DO NOT:
- Ask the user for input — the system decides autonomously
- Document trivial changes — skip them silently
- Write solutions that just describe the diff without insight
- Skip the prevention strategy — this is the compounding value