compound

name

compound

description

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.

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:

# 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 (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.