# Compound

> Use when finishing a non-trivial task, fixing a bug, completing a feature, or wrapping up a session and you want the work to make the system smarter next time. Runs the compound loop — consult memory, do the work, verify with an independent subagent (max 3 cycles), then distill only CONFIRMED lessons into STATE.md and memory. Triggers on "compound", "make this stick", "close the loop", or end-of-task wrap-up.

- Skill: `sethdford/compound` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add sethdford/compound`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/compound/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/compound

---


# Compound — the self-improving loop

Make this session leave the next one smarter. The loop enforces the five-stage progression
**fail → investigate → verify → distill → consult**. The discipline that matters is
**never writing a lesson until an independent verifier has confirmed it (stage 3) and you've
generalized it into a rule (stage 4)**. Logging raw failures is not compounding.

Create a TodoWrite item per step below and work them in order.

## Step 0 — CONSULT (read before doing)

- Read `STATE.md` at the repo root if it exists. If it doesn't exist and this is a real
  project, create it (automatically — don't ask) with exactly these sections:

```markdown
# Project memory · <PROJECT NAME>

## Now
<!-- what we're actively working on -->
## Verified facts
<!-- stage 3: things we stopped guessing about, each with how it was verified -->
## General rules
<!-- stage 4: distilled rules that apply beyond the specific case -->
## Open failures
<!-- stages 1-2: symptom · hypothesis · reproduction (command or file:line) -->
## Lessons learned
<!-- stage 4 distillations not yet promoted to rules -->
## Waiting for human
<!-- blocked items after 3 failed verify cycles: what's blocked · tried · needed -->
## Last session
<!-- stage 5 resume pointer: timestamp · what landed · what's next -->
```

(The same skeleton also ships as `STATE.template.md` beside this skill, with fuller comments.)
- Skim your Claude Code memory (the `MEMORY.md` index is auto-loaded into sessions). Pull the
  "Verified facts" and "General rules" into your working plan so you don't re-derive what's
  already known.

## Step 1–2 — WORK, then INVESTIGATE failures

- Do the task.
- When something fails, do **not** just move on. Spend a beat on *why*, then append to
  `STATE.md` → **Open failures** with: a one-line symptom, your current hypothesis, and a
  concrete reproduction path (command or file:line). This is stages 1–2.

## Step 3 — VERIFY (independent, max 3 cycles)

Dispatch the **`verifier`** subagent shipped with this plugin — do NOT grade your own work.
(It registers as `verifier`, or as `compound-loop:verifier` when installed as a plugin; either
name resolves.)

```
Agent(subagent_type: "verifier", prompt: "<what changed, the rubric/acceptance criteria,
       and where to find the artifacts>")
```

The verifier runs the project's tests/lint/build itself and returns `VERDICT: PASS|FAIL`
with evidence and gaps.

- **FAIL** → fix the named gaps, re-dispatch. Cap at **3 cycles**.
- **3rd FAIL** → stop. Write a clear entry under `STATE.md` → **Waiting for human**
  (what's blocked, what you tried, what you need) and surface it. Do not declare success.
- **PASS** → continue to distill.

If there are no runnable checks (e.g. docs/config), give the verifier explicit acceptance
criteria so it still grades against something concrete, not vibes.

## Step 4 — DISTILL (only after PASS)

Turn the verified outcome into a **general rule**, then write it to the right scope:

- **Project-specific fact or rule** → `STATE.md` (Verified facts / General rules).
- **Cross-project rule** ("X always breaks on Y") → a new file in your Claude Code user
  memory directory + a one-line pointer in `MEMORY.md`.
- **A repeatable procedure** → sharpen the relevant **skill** (add a "Known failure modes"
  or "Anti-patterns" note). Procedural memory travels further than a state file.

Write the *generalization*, not the incident. "Auth middleware must be rate_limit → jwt →
rbac; reversing causes 401s" — not "fixed the 401 today."

## Step 5 — POINTER (resume, don't restart)

Update `STATE.md` → **Last session**: timestamp, what landed, what's next. The next session
reads this first and resumes instead of rediscovering.

## Guardrails

- **Maker never grades maker.** Verification is always the `verifier` subagent.
- **No unverified lessons.** Distillation is gated on a verifier PASS.
- **Respect the memory budget.** Only the first ~200 lines / 25 KB of `MEMORY.md` auto-loads
  into subagents. Keep the index lean; consolidate when it grows.
- **Bias to honesty.** If the verifier couldn't actually run the checks, treat it as not
  verified — write to "Waiting for human," not "Verified facts."

## Provenance

Patterns adopted from [`cobusgreyling/loop-engineering`](https://github.com/cobusgreyling/loop-engineering)
(five primitives, state file, the "Verifier Theater" failure mode; endorsed by Boris Cherny)
and Anthropic's official sub-agents / memory-tool docs. Full design in `docs/DESIGN.md`.