Compound — Compounding Knowledge Loop
Announce at start: "I'm using the compound skill to document this so it makes future work easier."
Overview
Captures a solved problem while context is fresh into docs/solutions/<category>/<slug>.md, with
YAML frontmatter for search and dedup. The store is committed with the repo, so it travels with
the code and benefits collaborators and future agents.
Why "compound"? The first time you solve a problem it takes research. Document it, and the next occurrence takes minutes. Each unit of engineering work should make subsequent units easier — not harder.
The closed loop: this skill is the write side. The read side is any agent (including
lfg Step 1) searching docs/solutions/ before starting work — which only happens if the store
is discoverable, so the Discoverability Check below is mandatory.
Modes
| Mode | When | Behavior |
|---|---|---|
| Interactive (default) | no mode:headless token |
Ask Full vs Lightweight, end with a "What's next?" prompt. |
| Headless | mode:headless in $ARGUMENTS |
No questions. Run Full. Apply the discoverability edit silently if needed. End with a structured terminal report. |
Strip mode:headless from $ARGUMENTS before treating the remainder as the brief context hint.
Preconditions (advisory)
- The problem is solved, not in-progress.
- The solution is verified working.
- It is non-trivial (not a typo or an obvious one-liner). If trivial, in headless mode emit
Documentation skippedwith a reason; in interactive mode say so and stop.
Full Mode
Phase 1 — Research (parallel subagents)
Use references/dispatching-parallel-agents/SKILL.md to launch these three in parallel. Each returns
text only. Pass the relevant support-file contents into each task prompt so subagents have the
contract without cross-skill paths.
Context Analyzer — read
references/schema.md. Determine the track (bug vs knowledge) from the problem, the category, the frontmatter skeleton (must includecategory:), and a suggested filename<sanitized-problem-slug>.md(no date suffix; thedate:field is canonical). Readreferences/categories.mdfor the problem_type → directory mapping.Solution Extractor — pull the substance from the conversation. Conversation history and the verified fix take priority over everything else.
- Bug track: Problem · Symptoms · What Didn't Work · Solution (with before/after code) · Why This Works (root cause) · Prevention.
- Knowledge track: Context · Guidance · Why This Matters · When to Apply · Examples.
Related Docs Finder — grep
docs/solutions/for overlap (frontmatter-first filtering: rungrep -iontitle:,tags:,module:,component:before reading bodies; read full text only for strong matches). Score overlap across five dimensions (problem, root cause, solution, referenced files, prevention):- High = 4-5 match (same problem solved again)
- Moderate = 2-3 match (same area, different angle)
- Low = 0-1 match. Return links, relationships, and the overlap score + matched dimensions.
Phase 2 — Assemble & write
WAIT for all Phase 1 subagents to finish, then the orchestrator (main context):
Collect the text results.
Act on the overlap score:
Overlap Action High UPDATE the existing doc with fresher context; keep its path/structure; add last_updated: YYYY-MM-DD. Do not create a duplicate.Moderate Create the new doc; note the related doc for a future consolidation pass. Low / none Create the new doc. Assemble the markdown from
assets/solution-template.md(preserve section order).Validate frontmatter against
references/schema.md. Quote any scalar value containing#or:and quote every array item — these silently corrupt YAML parsing.mkdir -p docs/solutions/<category>/and write the file.You do NOT need to hand-maintain
docs/solutions/index.md— theindex-solutionsPostToolUse hook rebuilds it automatically (pure bash, no LLM) whenever a solution file changes, and theinject-solutions-indexSessionStart hook injects that index into every future session. That injection is the always-on read side of the loop; the Discoverability Check below is the durable fallback for sessions/agents running without these hooks.
Phase 3 — Discoverability Check (always runs)
The store only compounds value if agents can find it.
Identify which root instruction file holds substantive content —
AGENTS.md,CLAUDE.md, or both (one may be a shim that@-includes the other; edit the substantive one). If neither exists, skip this phase.Assess whether an agent reading it would learn: (a) a searchable solutions store exists, (b) enough structure to search it (category dirs, frontmatter fields
module/tags/problem_type), (c) that it's relevant when implementing or debugging in documented areas. This is a semantic check, not a string match.If the spirit is already met, do nothing.
If not, add the smallest natural addition. Prefer one line in an existing architecture/ directory/docs section over a new heading. Keep the tone informational, not imperative — "relevant when implementing or debugging in documented areas," never "always search first."
Example line for a directory/architecture listing:
docs/solutions/ # documented solutions to past problems (bugs + knowledge), by category, with YAML frontmatter (module, tags, problem_type)In interactive mode, show the proposed edit and get consent (use
AskUserQuestion; load its schema withToolSearch select:AskUserQuestionfirst if needed) before editing. In headless mode, apply it silently and report it.
Lightweight Mode (interactive only)
Single pass, no subagents — same doc, fewer tokens, no overlap detection. The orchestrator does
it all sequentially: extract problem+solution from the conversation → classify track/category/
filename via the reference files → write docs/solutions/<category>/<slug>.md from the template
with the track-appropriate sections. Then run the Discoverability Check. Headless never enters
Lightweight.
Output
Headless
✓ Documentation complete (headless mode)
File: docs/solutions/<category>/<slug>.md (created | updated)
Track: <bug | knowledge>
Overlap: <none | low | moderate — see <path> | high — existing doc updated>
Instruction-file edit: <none needed | applied to <path>>
Documentation complete
If nothing was written (e.g. trivial / unsolved):
✗ Documentation skipped (headless mode)
Reason: <one sentence>
Documentation skipped
Interactive
Report the file written, the track/category, overlap result, and any discoverability edit, then
present a "What's next?" prompt via AskUserQuestion.
Auto-invoke
Trigger phrases that suggest offering to compound: "that worked", "it's fixed", "working now",
"problem solved". Manual: /compound [context] to document immediately.