The Compounding Knowledge Lifecycle

How a lesson learned once keeps paying: captured, stored, found, and kept true.

1. The premise

Compound engineering makes one bet: each unit of work should make the next unit easier. Code alone doesn't do that; code makes the product better, not the process. The thing that compounds is knowledge: every solved problem, named concept, and hard-won convention gets written down in a shape that future work can find at the exact moment it needs it.

That last clause is the whole game. Teams write postmortems all the time; they rot in wikis because nothing ever reads them again. This system closes the loop by making retrieval a built-in step of five different skills, not an act of discipline: planning greps docs/solutions/ before it structures a plan, review audits the diff against it, and every other stage reads the same memory on its way in.

Down arrows: any stage can write a learning. Dashed up arrows: every stage reads the memory as grounding.

Everything below is a tour of that return arrow: what flows through it, where it rests, how it gets picked back up, and how it's kept from going stale.

2. What a learning actually is

The unit of compounded knowledge is a learning (also called a solution doc): one markdown file documenting one solved problem, stored under docs/solutions/<category>/. Here's a real one, the frontmatter of the most consequential learning in this repo:

---
title: Always-on routing for interactive menus belongs inline in
       SKILL.md, not in references
date: 2026-04-28
category: skill-design
module: compound-engineering
problem_type: architecture_pattern
component: ce-plan
severity: medium
applies_when:
  - Authoring a skill that ends in an AskUserQuestion-style menu
  - Deciding whether per-option routing belongs in SKILL.md or a reference
  - Reviewing a skill where the agent renders a menu and stops
    at the user's selection without acting
tags: [skill-design, menu-routing, skill-md-vs-references, ce-plan,
       extraction-rule, load-bearing-rules]
related_issue: https://github.com/EveryInc/compound-engineering-plugin/issues/714
---

Every field earns its place by serving search, not narrative:

Field	What it's for at retrieval time
`title`	The most descriptive grep target, searched first
`tags`	Synonym surface: the searcher greps `tags:.*(menu\|routing\|handoff)` without opening a single file
`module` / `component`	"Is this about the area I'm touching?"
`problem_type`	The track switch (see below)
`applies_when`	The self-selection test: a future agent reads these three lines and knows in seconds whether to keep reading
`severity`	Ranking when many docs match
`date`	Staleness signal: old learnings get healthy suspicion

problem_type splits into two tracks:

Bug-track covers what broke: runtime_error, test_failure, performance_issue, security_issue, integration_issue, logic_error…
Knowledge-track covers what was decided or discovered: architecture_pattern, design_pattern, tooling_decision, convention, workflow_issue, best_practice…

A knowledge system that only remembers bugs forgets most of what a team learns. This repo's memory is mostly knowledge-track. Its live census today:

One tier sits above learnings: the pattern doc: guidance generalized from several learnings into a broader rule, higher leverage and (for exactly that reason) higher risk when stale. This repo hasn't promoted any yet; the convention (docs/solutions/patterns/critical-patterns.md) is a slot waiting for enough sibling learnings to deserve generalizing.

3. Birth: how a learning gets captured

The capturing skill is /ce-compound, and its core discipline is timing: document the solution while the context is still fresh: same session as the fix, while the failed attempts, the actual root cause, and the "oh, THAT's why" are all still in the conversation. A week later, that context is gone and the write-up degrades into a summary.

Mechanically, a compound run fans out subagents so the orchestrator's context stays clean:

a context analyzer works out the category, filename, and frontmatter skeleton,
a solution extractor writes the prose body (problem, investigation, solution, prevention),
a related-docs finder checks for overlap with existing learnings, so near-duplicates get merged or cross-linked instead of accumulating,

…and then the orchestrator alone writes exactly one doc into docs/solutions/; subagents never touch tracked files.

Capture has more than one doorway. The full interactive /ce-compound after a gnarly fix is the main one, but knowledge also arrives via:

/ce-debug offering a compound step after a root-cause fix,
/ce-pov: say "compound it" after a verdict and the decision lands as a tooling_decision learning, headlessly,
lightweight mode for small lessons (skips the overlap check; the refresh cycle catches any duplicate later).

The life of one learning

The best way to see the loop is to follow that frontmatter from section 2 end to end:

One incident, four durable artifacts: a fix, a learning, a test, a doctrine. That's what "compounding" means concretely: not that documents accumulate, but that failure classes get retired. What happened to this particular learning two months later closes the tour (section 7).

4. Where knowledge lives: the memory map

Not everything the system knows lives in one place, and the tiers differ on one axis: durability.

The map carries the what and where; the detail it can't hold is how each tier grows. docs/solutions/ answers "has anyone here hit this before?" and grows through /ce-compound. CONCEPTS.md accretes as a side effect of compounding; yesterday's ce-explain work added Explainer and Check-in the moment the dialogue settled their meanings, not after. STRATEGY.md is read as grounding by ideate, brainstorm, and plan. And plans are never edited after execution, so they still explain why months later.

The design rule that separates the columns: knowledge you'd mourn goes in git; knowledge you can re-derive goes in /tmp.

5. Detection: how the past finds you

Nothing in this system pushes knowledge at you. There is no digest, no "please read the wiki." Instead, five skills pull from the memory at exactly the moment they're making decisions, through a shared retrieval protocol called the learnings-researcher.

The protocol is grep-first, because the memory is designed to be searched without being read:

Who pulls, and what they do with it:

Consumer	Moment	Effect
`/ce-plan`	before structuring a plan	learnings become constraints and KTDs
`/ce-brainstorm`	while grounding requirements	prior decisions shape scope
`/ce-code-review`	always-on reviewer in every review	each relevant learning gets a followed / violated verdict against the actual diff
`/ce-ideate`	while generating ideas	past dead-ends prune the idea space
`/ce-debug`	while hypothesizing	known root-cause patterns jump the queue

The review integration is the sharpest tooth: a violation is a finding with a file:line, not a suggestion. (Section 7 shows this firing on a real feature.)

Two trust rules keep detection honest:

Present evidence wins.If a learning claims something the current code contradicts, the researcher flags the conflict rather than echoing the claim; learnings can be superseded, and a confidently wrong memory is worse than none.
Date is signal.Every surfaced learning carries its date so the consumer can weigh whether the world has moved.

6. Refresh: how knowledge stays true

Memory that only grows eventually lies. Code moves on; learnings stand still. Three counter-forces keep the memory truthful, each operating at a different tempo:

At read time: the cheapest guard, already covered in section 5.
At write time: when /ce-compound adds or edits a CONCEPTS.md entry, it must also inspect that entry's coherence neighborhood (the sibling terms it references) and fix drift it has evidence for. Bounded on purpose: neighborhood only, never a full-file audit on a hunch.
On demand: /ce-compound-refresh is the deliberate sweep, and its most important property is that it is not a default follow-up. It runs when there's a reason: a new learning contradicts an older one, a pattern doc looks obsolete, an area's docs predate a big refactor. And it takes a scope hint (/ce-compound-refresh payments) because a full-corpus refresh is almost never the right spend.

7. The whole loop, told through one feature

Yesterday this repo shipped a new skill, /ce-explain, end to end. Watch the knowledge system fire at every stage; this all actually happened:

Brainstormpulled the repo-profile from the shared cache (miss → derived → persisted for the next nine skills) and scanned for prior art before asking a single question.
Planning researchsurfaced five learnings as inputs. Three were markedmust-apply during authoring: inline menu routing (#714's legacy),$ARGUMENTSportability, and theSKILL_DIRscript anchor. The plan's Key Technical Decisions cite them.
Implementationfollowed them, and where a learning prescribed a guard, the new skill grew its own mirror regression test.
Reviewaudited the diff against eight learnings: all followed. Separately, its validators used the AGENTS.md doctrine (born from a learning) toreject a reviewer's proposed fixthat would have reintroduced the original failure mode. The memory didn't just inform the work; it defended it.
Vocabulary compounded:ExplainerandCheck-inenteredCONCEPTS.mdthe moment the brainstorm resolved their meanings.
The residue became future knowledge: one review finding was deliberately deferred and filed as issue #1057. If its fix teaches something durable,/ce-compoundwill mint learning #36, and the loop starts again.

No step required anyone to remember to consult the memory.

8. Why it compounds, and the failure modes it dodges

The financial metaphor is earned. Each learning is principal; every retrieval that changes a decision is an interest payment; and pattern docs are reinvestment: several payments consolidated into a higher-yield instrument. The census above (35 docs) is a balance sheet.

Knowledge systems usually fail in predictable ways:

Failure mode	Counter-measure
Write-only graveyard: docs nobody reads	Retrieval is a built-in step of five skills, not a human habit
Unfindable memory: knowledge exists but search misses it	Frontmatter is designed for grep: tags, module, problem_type, applies_when
Confident staleness: old docs override current reality	Present-evidence-wins at read time; dates surfaced; refresh on contradiction
Duplicate sprawl: five docs, one lesson	Related-docs finder checks overlap before every write
Capture decay: lessons written a week late, from fading memory	Compounding is the pipeline's closing step, run while context is fresh
Speculative patterns: grand rules with no evidence	Pattern docs are promoted from multiple learnings, never authored cold

None of these guards is heroic. Each is a small structural choice: a frontmatter field, an always-on subagent, a rule about who writes which file. Which is the quiet thesis of the whole system: compounding isn't a documentation culture, it's an architecture. The knowledge flows because the pipes are built into the skills people already run.

Grounded in the live repo, July 2026: docs/solutions/, ce-compound, ce-compound-refresh, the learnings-researcher persona, and the ce-explain feature shipped yesterday as the worked example.