How a fleet skill or review turns a finding into a durable rule, instead of fixing it once and forgetting.
Each unit of engineering work should make subsequent units easier, not harder. A bug fix that doesn't update the rule that allowed the bug is a half-finished job: the next change in the same area will hit the same class of bug, and the cycle repeats.
Three places a lesson can land in this fleet:
| Where | When | Effect |
|---|---|---|
| CLAUDE.md fleet rule | The mistake recurs across repos or is a fleet-wide invariant | Every fleet repo inherits the rule on next sync |
.claude/hooks/* block |
The mistake is mechanical and can be detected from tool input/output | Hook blocks the next attempt before the file is written |
| Skill prompt update | The mistake is judgment-shaped (review pass missed a class of finding) | Future runs of that skill catch the variant |
Compound a lesson only when one of these is true:
- Recurrence — the same kind of bug has now appeared 2+ times. Write down the rule that would have caught both.
- High blast radius — the bug shipped, broke a downstream user, or required a revert. The rule prevents the next shipping incident.
- Drift signal — fleet repos disagreed on the answer. The rule reconciles which answer wins.
Don't compound for one-off fixes that won't recur. Don't write a "lesson" doc when the lesson is just "we fixed it." The fleet rule is the lesson; if you can't crystallize it into a rule, the lesson isn't ready.
- Name the rule — one sentence, imperative voice. "Never X." "Always Y."
- Cite the incident — one-line
**Why:**line referencing the commit, PR, or finding. Don't write a paragraph. - State the application — one-line
**How to apply:**line saying when the rule fires. - Land it where it'll fire — CLAUDE.md, hook, or skill prompt. Pick the lowest-friction surface that catches the next occurrence.
Skip the retrospective doc. Skip the post-mortem template. The rule is the artifact.
- The "lessons learned" graveyard — a
docs/lessons/folder where dated markdown files rot. Don't. The rule belongs in the live config that fires on the next run. - Vague rules — "be careful with X." Useless. If you can't write the rule as a
rgpattern or a CLAUDE.md🚨line, it isn't a rule yet. - Rules without why — future readers can't judge edge cases without the original incident. Always cite.
Borrowed from Every Inc.'s Compound Engineering playbook (https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents). Their /ce-compound slash command is the verb form of this principle; we encode the same discipline as a fleet convention rather than a slash command.