# ce-compound

> A skill from Every's compound-engineering plugin that captures a just-solved problem into searchable team knowledge under `docs/solutions/`, coordinating parallel subagents to extract context, name the solution, detect duplicates, and seed the project's `CONCEPTS.md` vocabulary. Its companion `ce-compound-refresh` audits those learnings against the evolving codebase and decides whether to keep, update, consolidate, replace, or delete each one.

**Use case**: Turn a solved problem into reusable team knowledge while the context is fresh — and keep that knowledge from rotting as the code moves

**Canonical URL**: https://agentcookbooks.com/skills/ce-compound/

**Topics**: claude-code, skills, knowledge-codification, documentation

**Trigger phrases**: "document this solution so we don't solve it twice", "compound this learning", "refresh the stale docs under docs/solutions"

**Source**: [Every](https://github.com/EveryInc/compound-engineering-plugin/tree/main/plugins/compound-engineering/skills/ce-compound)

**License**: MIT

---

## What it does

`ce-compound` is the signature skill of [Every's compound-engineering plugin](https://github.com/EveryInc/compound-engineering-plugin) — see [skills/ce-compound](https://github.com/EveryInc/compound-engineering-plugin/tree/main/plugins/compound-engineering/skills/ce-compound). It exists to make the loop the plugin is named for real: each unit of engineering work should make the next one cheaper. When you've just solved and verified a problem, `ce-compound` captures the solution while the context is still fresh and turns one-time effort into a reusable lookup.

It coordinates parallel subagents to extract the context, identify the actual solution, and find related existing docs, then assembles a structured Markdown file at `docs/solutions/[category]/[filename].md` with searchable YAML frontmatter. It offers two modes: **Full** (recommended — cross-references existing docs and detects high-overlap duplicates, *updating* them instead of writing a new one) and **Lightweight** (a faster single pass). It also seeds and maintains `CONCEPTS.md`, the project's shared domain vocabulary, and makes small discoverability edits to `AGENTS.md` / `CLAUDE.md` so future agents can find the knowledge store. A `validate-frontmatter.py` script keeps the YAML schema consistent.

Its companion **`ce-compound-refresh`** is the other half of the lifecycle: it audits the accumulated `docs/solutions/` against the *current* codebase, detecting drift in file paths, code examples, or recommended approaches, and classifies each doc as **Keep, Update, Consolidate, Replace, or Delete**. It runs interactively by default (asking only on ambiguous cases) or in `mode:headless` (auto-executes the unambiguous actions and flags borderline ones as stale). Where `ce-compound` captures, `ce-compound-refresh` keeps the knowledge base from rotting as the code moves underneath it.

## When to use it

- Right after solving a non-obvious bug or making a hard-won decision — capture it before the context evaporates
- When the same problem has now been solved twice — the second time is the signal it belongs in `docs/solutions/`
- Seeding a shared `CONCEPTS.md` vocabulary so agents and humans use the same terms for the same things
- Periodically (or in a maintenance pass) running `ce-compound-refresh` to catch learnings that have drifted out of sync with the code

When *not* to reach for it:

- Mid-problem — `ce-compound` documents *solved and verified* problems, not open investigations
- For end-user product docs — this is internal engineering knowledge, not customer-facing documentation
- As a commit message or PR description — that's `ce-commit` / `ce-commit-push-pr` territory

## Install

Part of the compound-engineering plugin (not a standalone `~/.claude/skills/` drop-in). In Claude Code:

```
/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering
```

Then invoke `/ce-compound` after a solved problem, and `/ce-compound-refresh` to maintain the store. The plugin namespaces every skill with `ce-` to avoid collisions, and also targets Codex and Cursor. MIT-licensed.

## What a session looks like

1. **Solve and verify first.** You've just chased down why a background job silently dropped records and shipped the fix.
2. **Invoke `/ce-compound`** with a one-line context note. Choose **Full** mode.
3. **Subagents fan out.** One extracts the context (what broke, why), one names the solution, one searches `docs/solutions/` for overlap.
4. **Duplicate check.** If a near-identical doc exists, the skill updates it rather than creating a second; otherwise it writes `docs/solutions/[category]/[filename].md` with frontmatter (symptoms, root cause, fix, tags).
5. **Vocabulary capture.** Any new domain term is added to `CONCEPTS.md`; a discoverability line goes into `AGENTS.md` / `CLAUDE.md` so the next agent reads the store.
6. **Later — `/ce-compound-refresh`.** Weeks on, the job runner was rewritten. Refresh investigates the doc against the new code, sees the file paths moved, and classifies it **Update** — rewriting the stale paths and code sample while leaving the root-cause narrative intact.

The discipline that makes it work: the payoff is deferred. The first capture costs research time you've *already spent*; the compounding only shows up on the second and third encounter, when a 30-minute rediscovery becomes a 30-second lookup. `ce-compound-refresh` is what keeps that lookup trustworthy.

## Receipts

Run 2026-06-04 by following the upstream `ce-compound` `SKILL.md` procedure step by step — the skill's logic is plain instructions plus subagent coordination, so it can be executed by hand. (A true `/plugin install` invocation wasn't used; this is the procedure emulated faithfully, named as such.) The target was a real, just-solved problem: why `noindex` topic pages were leaking into `sitemap-0.xml`, captured into the skill's `docs/solutions/` store. What the run surfaced:

- **The schema assumes a Rails stack.** The frontmatter `component` enum is entirely Ruby/Rails (`rails_model`, `hotwire_turbo`, `service_object`, `background_job`, …), so a Node/Astro project has no clean fit — `tooling` was the least-bad choice. The *frame* — Bug vs. Knowledge track, symptoms → root cause → prevention — is stack-agnostic and genuinely useful; the *enums* (and a `rails_version` field) betray the plugin's 37signals heritage, the same one `ce-dhh-rails-style` is built on.
- **Phase 2 validation needs Python 3.** The skill prescribes `python3 scripts/validate-frontmatter.py`, re-run until exit 0. A pure-Node repo has no Python — here `python3` resolved only to an OS stub. The script itself is 137 lines, pure-stdlib, read-only: three regex parser-safety checks (delimiter lines must be exactly `---`; no unquoted ` #`; no unquoted `: ` in top-level scalars). Porting those three checks to Node passed the artifact at exit 0. Worth knowing before adopting: the validation step isn't language-neutral.
- **The auto-memory scan (Phase 0.5) actually fired.** On Claude Code the skill scans the session's auto-memory for relevant context; a scoped note covering this exact gotcha matched, and — as instructed — the live session's edits took priority over the memory as evidence. The skill is genuinely Claude-Code-aware, not a generic prompt.
- **Vocabulary stays separate from solution detail by rule.** `CONCEPTS.md` explicitly excludes file paths, identifiers, and version claims, so the brittle two-file / constant-name specifics live only in the `docs/solutions/` doc while `CONCEPTS.md` holds the durable nouns (topic page, noindex topic, boilerplate tag).

Verdict: the compounding *concept* is real and stack-agnostic; the *implementation* is Rails/Python-shaped. The deferred payoff is by design — the win lands on the second encounter, when a re-derivation becomes a lookup. Not yet exercised: the high-overlap **update** branch (needs a second run) and `ce-compound-refresh` on a genuinely drifted doc.

## Source and attribution

From [Every's compound-engineering plugin](https://github.com/EveryInc/compound-engineering-plugin/tree/main/plugins/compound-engineering/skills/ce-compound) — the MIT-licensed plugin (Dan Shipper & Kieran Klaassen) that packages the Plan → Work → Assess → Compound workflow Every uses across its products.

License: MIT.

The skill is the literal implementation of the plugin's thesis, quoted verbatim: *"Each unit of engineering work should make subsequent units easier — not harder."* `ce-compound` is where that "easier next time" gets written down; `ce-compound-refresh` is where it's kept honest.