# Compound Knowledge

> Captures a solved non-trivial problem as a searchable markdown doc in docs/solutions/ (root cause, fix, prevention, keywords), and searches that folder before starting new non-trivial debugging so past solutions get reused instead of re-derived from scratch. Use right after fixing a tricky bug, working around a gotcha, or solving something that took real investigation — and before diagnosing a new problem that might already have a documented answer.

- Skill: `jsvillalbat/compound-knowledge` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jsvillalbat/compound-knowledge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jsvillalbat/compound-knowledge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: jsvillalbat (https://skillmd.com/u/jsvillalbat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jsvillalbat/compound-knowledge

---


# Compound Knowledge

Every hard-won fix that only lives in one session's context gets re-derived from
scratch the next time it comes up — in a different session, by a different agent, or
by the same agent six months later with no memory of last time. This skill turns a
solved problem into a searchable artifact so the investigation compounds instead of
repeating.

## When to use this

- **Capture** right after closing out a problem that took genuine investigation: a
  non-obvious root cause, a workaround for a library/platform quirk, a gotcha that
  will plausibly bite again. Not "fixed a typo" — that doesn't need a doc.
- Triggered by the user saying "that worked," "remember this," or on your own
  initiative right after verifying a hard-won fix (see
  [`verify-before-done`](../verify-before-done) — don't document a fix you haven't
  actually confirmed works).
- **Search** before starting non-trivial debugging or investigation — check
  `docs/solutions/` first in case this was already solved.

## Instructions

### Capturing a solution

1. **Confirm it's actually solved.** Don't write up a fix you're only hoping works —
   verify it per `verify-before-done`'s evidence ladder first.
2. **Check for a near-duplicate first.** Search `docs/solutions/` by keyword/category
   — if this updates or extends an existing doc rather than being genuinely new,
   update that file instead of creating a near-duplicate.
3. **Pick a category** from a small fixed set so the folder stays scannable:
   `build-errors`, `runtime-bugs`, `performance`, `security`, `integration-config`,
   `tooling`. If nothing fits, it's fine to add a new category — just keep the set
   small.
4. **Write one file** at `docs/solutions/<category>/YYYY-MM-DD-<kebab-description>.md`
   using the template in `references/template.md`. Cover, in your own single pass
   (no need for separate sub-analyses — one thorough pass covering all three angles is
   enough):
   - **Problem** — the symptom, how it showed up, what it looked like from the outside.
   - **Root cause** — what was actually wrong, not just what fixed it.
   - **Solution** — what changed, with file:line references where useful.
   - **Prevention** — how to catch this earlier next time: a test to add, a check, a
     convention.
   - **Keywords** — terms someone would actually search for when hitting this again,
     including error message fragments.
5. **Consider a targeted follow-up check** proportional to the category — a security
   fix might warrant checking for the same pattern elsewhere in the codebase; a
   performance fix might warrant a benchmark; a build fix might warrant confirming the
   full test suite still runs clean.

### Searching before investigating

1. Before diving into a new non-trivial problem, grep/glob `docs/solutions/` for
   matching keywords, error text, or category.
2. If a match exists, read it fully before starting fresh investigation — apply it
   directly if the situation matches, or note explicitly why this case differs if it
   doesn't quite fit.
3. If no match exists, proceed normally — and capture the result per the steps above
   once solved.

## Reference files

- `references/template.md` — the blank solution-doc template.
- `references/example.md` — one filled-in worked example.