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