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