What Comes After Acting
Ch5 ended on a clear boundary: zero unreviewed external action. Rules fire on their own; the writing twin drafts on demand. Nothing sends without me reading it first. That’s a stable design.
What it doesn’t answer is the question underneath it. If agents are acting autonomously—loading context, drafting messages, surfacing reminders—how do you keep them from getting worse at those jobs over time? The answer isn’t a better model. It’s a feedback loop that reads the agents’ own failure record and proposes structural fixes to the instructions they run on.
The Failure Log Reads Itself
Two agents log verdicts after every significant output: qa-validator for research and code, voice-qa for writing drafts. Every PASS, REVISE, and FAIL lands in .claude/context/qa-log-YYYYMMDD.md. That’s the substrate. /evolve reads those logs across a configurable window—7 days, 30 days, everything—groups failures by agent, and categorizes each one. Six categories: voice/tone, scope drift, hallucination, format, safety, overreach.
Then it scores severity. Three or more of the same failure type in one agent is a systematic prompt gap. Two is an emerging pattern. One is probably contextual—noted, not actioned.
The categorization step does something I couldn’t do manually at scale: it surfaces which agents are accumulating the same kind of mistake across different sessions, even when no single session looked alarming.
Prompt Edits As Patches
For every high-severity pattern, /evolve traces back to the agent’s definition file and diagnoses: is the rule missing, present but ambiguous, contradicted by another rule, or present but consistently ignored?
The research-analyst agent was citing URLs from memory—auth-walled pages on LinkedIn, theorg.com, Crunchbase—that looked plausible but couldn’t be verified. A soft self-check rule existed in the agent definition. It wasn’t holding. The diagnosis was enforcement: the rule existed, but the model was self-assessing URL authenticity unreliably, constructing plausible-looking paths from domain knowledge rather than from actual tool results.
The fix wasn’t a reminder. It was a structural prohibition: an explicit blocklist of auth-walled domains that must never have specific URLs cited, regardless of how confident the agent feels.
The proposal staged to .claude/context/evolve-proposals-20260510.md. I reviewed it, approved it, applied it. The constraint does what the behavioral reminder couldn’t, because it removes the agent’s discretion on the specific failure surface.
Did the Fix Actually Fix It
This is where most prompt-engineering writeups stop. Apply the edit, move on. The loop doesn’t close there.
After an edit lands, the next /evolve run measures whether the failure category recurs in subsequent QA logs. Zero recurrences is resolved. A recurrence means the fix didn’t hold—back to diagnosis with a clearer failure signal and elevated severity.
A count-verification rule I added to claude-code-expert corrected the problem for hook counts, but the agent didn’t generalize it to slash commands—same class of failure, different surface, and the rule was too narrow to cover it. A third version generalized the rule: any inventory that can be enumerated via grep or a directory listing is enumerable; no “unverified” hedging allowed when the source is a file you can read.
There’s a subtler problem the measurement step catches. An edit can look resolved simply because the agent was never exercised on the relevant task—zero recurrences conflating “fixed” with “never re-tested.” The system holds an edit as “measuring, no coverage” until the agent produces output in the relevant category and passes. Without that gate, 5 entries were false-resolved in a single run.
What Stays Manual
The loop handles the mechanical part. What stays human is the choice of which proposed edits actually land.
/evolve stages proposals and stops. Every one gets a human review before applying. The reasoning is the same as Ch5’s line about external actions: a bad prompt edit propagates through every future run of that agent. The review step is cheap relative to the compounding cost of a wrong fix.
There’s also a thing the measurement loop doesn’t catch on its own: cross-agent patterns. Per-agent analysis flags repeated failures within one agent, but single-instance hallucinations across different agents don’t surface in any one agent’s record. In early 2026, three agents produced one fabricated output each across three months. Each instance looked like a one-off contextual failure. Scanning all QA logs together, the pattern was clear: a system update had outpaced context propagation across three agents before corrections landed. That diagnostic pass was manual. The system doesn’t close that loop automatically yet.
I’ve spent years learning to catch my own mistakes before they ship. /evolve is that habit, externalized—the system does to its agents what I’ve always done to myself.
It doesn’t make the AI smarter. It makes it accountable to its own record. The fixes are automatic. The judgment of which ones to keep is still mine.
Start at the beginning: Chapter 0—I Gave Claude a Brain. Here’s What Happened. · Previous: Ch5—When Your AI Starts Thinking For You