An expert agent is a closed loop — Act produces work, Learn updates the mental model, Reuse reads it before the next act — and breaking any one step collapses you back to a generic agent.

Principle

Act · Learn · Reuse

The shape

A loop, not a pipeline.

Each cycle's Reuse becomes the starting context for the next Act. The mental model accumulates across sessions.

① Act

Do real work

plan, build, fix, answer — in the domain

→

② Learn

Update the model

reconcile expertise.yaml against post-action disk state

→

③ Reuse

Read before acting

next agent consumes the updated model first

closes the loopReuse ↻ Act — the model compounds

Subtract any step and the loop breaks — you're back to a generic agent.

The three ways it fails

Each step is necessary. None is sufficient.

✗ No Act

Self-improve runs on a cron with nothing to learn from.

no work →

model drifts toward memory→

no grounding in real code

✗ No Learn

Humans edit expertise.yaml by hand. File ages out.

code changes →

stale claims persist→

next Reuse ships misinformation

✗ No Reuse

Expertise accumulates. No surface reads it before acting.

Learn runs →

model sits on disk→

cost paid, zero benefit

The most common violation is No Reuse — teams build expertise files nobody reads.

Why it compounds

Generic agents restart at zero. Experts start where the last one stopped.

Same task, three sessions. Watch what each agent brings to Act #3.

Generic agent — line

Act 1(from zero)

Act 2(from zero)

Act 3(from zero)

Every session rediscovers the codebase. No cumulative advantage.

Expert agent — loop

Act 1 → Learn → Reuse

Act 2 → Learn → Reuse

Act 3(from accumulated model)

Act 3 starts where Act 2 left off. Specialization compounds.

Why this isn't just "documentation"

Three reasons docs fail where the loop works.

Who's the reader?

humans (prose)

agents (structured YAML)

Who writes the update?

humans, by hand

self-improve (an agent run)

When does it get read?

selectively, maybe

first step of every surface

Docs are written by humans, for humans, read when someone remembers. That's three failure modes stacked.

Where the loop lives

Each step is a protocolized surface — not a habit.

self-improve.mdLearn

The Learn step made explicit. An agent run that validates the mental model against current disk state and writes the reconciled file.

plan / build / askReuse

"Read EXPERTISE_FILE first." Every domain-expert workflow begins by consuming the mental model before taking any action.

/feature · /fixAct

The triggering work. Real domain output — a plan, code change, or answer — that gives the next Learn step something to reconcile against.

FULL expert = 3 cmdsALR

plan + build = Act. improve = Learn. Next plan reads the updated expertise = Reuse. The whole principle, compressed into a three-command interface.

The discipline

An expert agent is the loop itself — not a smart prompt, not a fat file.

Executing and forgetting is the generic baseline. Executing, learning, and reading the lesson back on the next run is what separates expertise from repetition. Close the loop or stay generic.