compound-learnings
Skill0 starsChanged 4 months agoMITView on GitHub
After solving a non-obvious problem — a gnarly bug, a tricky integration, a surprising workaround — write the solution pattern to docs/solutions/ so future planning and debugging start from it instead of re-deriving it. Each unit of work should make the next one easier.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- parcadei/Continuous-Claudetheir own version, first seen Oct 17, 2026
- parcadei/Continuous-Claude-v2their own version, first seen Oct 8, 2026
- J03Fr0st/skillstheir own version, first seen Jul 24, 2026
- bokiko/continuous-claude-guidetheir own version, first seen Feb 1, 2026
- parcadei/Continuous-Claude-v3their own version, first seen Jan 14, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- parcadei/Continuous-Claude★ 3.9ksame name
- parcadei/Continuous-Claude-v2★ 3.9ksame name
- parcadei/Continuous-Claude-v3★ 3.9ksame name
- bokiko/continuous-claude-guide★ 0same name
- J03Fr0st/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository29 other files it gives its agents.
- adopt-existing-projectSkill
- adrSkill
- branch-conflict-checkSkill
- ci-watchSkill
- config-auditSkill
- cost-checkSkill
- coverage-ratchetSkill
- doc-syncSkill
- eval-harnessSkill
- flaky-triageSkill
- followup-trackingSkill
- incident-captureSkill
- kit-doctorSkill
- kit-updateSkill
- logging-initSkill
- migration-checkSkill
- new-project-bootstrapSkill
- nightly-auditSkill
- observability-checkSkill
- parallel-workSkill
- perf-budgetSkill
- pr-babysitterSkill
- pre-prSkill
- prompt-regressionSkill
- releaseSkill
- session-handoffSkill
- sync-healthSkill
- using-the-kitSkill
- writing-kit-skillsSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Run at the end of a unit of work whenever any of these happened:
- Distinctive: line 62
Keep the Symptom section verbatim-rich: future sessions find these entries by grepping error text, so paste the real message, not a …
- Very specific: line 82
When a solution graduates into real documentation (a docs page, a spec section, a code comment at the site), update those via doc-sync and …
- Distinctive: line 86
If the directory grows past ~50 entries, split by area subdirectory.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Compound Learnings
Profile-driven. Solutions live at <docs.dir>/solutions/, where docs.dir
is capabilities.docs.dir from .claude/kit.yaml (default: docs).
A hard-won insight that lives only in one session's context is lost the moment
the session ends. This skill closes the loop the follow-ups log opens: where
followup-tracking captures work still to do, this captures problems already
solved — so the next task (and the next agent) starts from the answer, not the
investigation.
When to run it
Run at the end of a unit of work whenever any of these happened:
- A bug took real investigation to root-cause (roughly: more than ~30 minutes, or more than one wrong hypothesis).
- You discovered a non-obvious constraint of a dependency, API, or tool — behavior its docs don't state or state misleadingly.
- You built a workaround whose reason-for-being is invisible from the code.
- You found the fast path through something the next agent would do the slow way (a build quirk, a test-environment trap, a flaky external service).
What does not belong: routine feature work, anything the project docs or
spec already cover (update those instead — doc-sync), and anything session-
specific with no future value. If it meets one of the criteria above, write
it — the entry costs 90 seconds, and a re-derived investigation costs far more.
Entry format
One file per solution: <docs.dir>/solutions/YYYY-MM-DD-<slug>.md.
# <Short title stating the problem, not the fix>
- **Date:** YYYY-MM-DD
- **Area:** <subsystem / dependency / tool>
- **Symptom:** <what you observed — error text, wrong behavior. Verbatim
fragments help future grep.>
## Root cause
<What was actually wrong, in 2–5 sentences.>
## Solution
<What fixed it. Include the exact command / config / code pattern.>
## How to recognize it next time
<The tell-tale signature — the log line, the error class, the smell that should
trigger "check docs/solutions" instead of a fresh investigation.>Keep the Symptom section verbatim-rich: future sessions find these entries by grepping error text, so paste the real message, not a paraphrase.
The read side — this is what makes it compound
Writing entries is half the loop. The other half:
- Before planning or debugging, grep the solutions directory for the area
and any error text you are seeing:
CLAUDE.md's "Before You Start a Task" list includes this step — keep it there.grep -ril "<error fragment or subsystem>" docs/solutions/ 2>/dev/null - On a hit, read the entry before forming hypotheses. Confirm it still applies rather than assuming, but start from it.
Lifecycle
- Entries are append-only history; do not rewrite them as understanding evolves — add a new entry that supersedes and link the old one.
- When a solution graduates into real documentation (a docs page, a spec
section, a code comment at the site), update those via
doc-syncand note the promotion at the top of the entry. Leave the entry in place — its symptom text is still the search key. - If the directory grows past ~50 entries, split by area subdirectory; never archive entries whose symptoms can still occur.
Output
## Compound Learnings
- Added: <docs/solutions/YYYY-MM-DD-<slug>.md — title / none this unit of work>
- Superseded: <entry link / none>
- Promoted to docs/spec: <where / none>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

