agentleFS
nfeuernfeuer/project-foundation-kit/.claude/skills/compound-learnings/SKILL.md

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

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
  1. Distinctive:

    Run at the end of a unit of work whenever any of these happened:

    line 24
  2. Distinctive:

    Keep the Symptom section verbatim-rich: future sessions find these entries by grepping error text, so paste the real message, not a …

    line 62
  3. Very specific:

    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 …

    line 82
  4. Distinctive:

    If the directory grows past ~50 entries, split by area subdirectory.

    line 86

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:
    grep -ril "<error fragment or subsystem>" docs/solutions/ 2>/dev/null
    CLAUDE.md's "Before You Start a Task" list includes this step — keep it there.
  • 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-sync and 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>

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.