A Domain Expert is a compound of 3–5 command surfaces sharing a knowledge layer plus a self-improve surface that validates the knowledge against real code — so the expertise can't go stale.

Pattern

Domain Expert

The shape

Not a file. A folder with three conceptual layers.

experts/database/

compound

├─expertise.yaml

Externalized mental model — file/line anchors, max 1000 lines

knowledge

├─question.md

Read-only surface — trace answers back to code paths

action · read

├─plan.md

Plan-mode surface — propose changes before executing

action · plan

├─build.md

Build-mode surface — execute work in the domain

action · write

└─self-improve.md

Re-reads code, re-verifies every claim, updates the yaml

maintenance

A single expert.md is not a Domain Expert — it's just a specialized command. The pattern requires at least two surfaces, one of which maintains the other.

How it stays alive

Action reads knowledge. Maintenance writes it back.

The action surfaces consume the knowledge layer; self-improve re-validates it against the code that just changed.

Knowledge

expertise.yaml

file paths · line numbers · verified claims

Maintenance

self-improve.md

re-reads code · re-verifies · validates yaml

→

reads

←

updates

Action · Read

question.md

"how does cost tracking work?"

Action · Write

plan.md · build.md

execute work inside the domain

Every claim in the yaml must resolve to a file + line re-read during the improve pass. No claim survives that can't be re-proved against disk.

The three shapes in practice

Pick by whether the expert answers, executes, or both.

ASK-focused

Answer questions. No code changes.

Kexpertise.yaml

Rquestion.md

Mself-improve.md

Read-only retrieval over an externalized mental model. e.g. database-expert

BUILD-focused

Plan, build, maintain. Expertise embedded.

K## Expertise (embedded)

Wplan.md

Wbuild.md

Mimprove.md

No separate yaml — each command carries its own ## Expertise section. e.g. cc-hook-expert

FULL

Ask AND execute. One shared yaml.

Kexpertise.yaml

Rquestion.md

Wplan.md

Wbuild.md

Mimprove.md

Emerges when a Question Expert grows to handle implementation too. e.g. websocket-expert

All three preserve the K · A · M triad. What varies is the number of action surfaces and whether knowledge is externalized or embedded.

Where does expertise live

Externalized OR embedded. Pick one per expert — never mix.

Source of truth

One file. yaml.safe_load() validates it.

Inline in each command file. N copies.

Best for

ASK-focused; multiple surfaces share one knowledge set.

BUILD-focused; commands need different depth of knowledge.

Self-improve job

Update one yaml. Re-validate syntax.

Update N sections. No structured validation.

Fails as

Extra redirection — commands must read the yaml before acting.

Silent divergence between command files if improve misses one.

Mixing the two creates a synchronization debt between two locations — exactly the drift the pattern exists to prevent.

What kills the pattern

Five failure modes — each collapses the self-healing loop.

Anti

One giant system prompt

Encodes all domain knowledge inline; stale within a week; no read/write separation; no code-validation hook.

Instead

Split into compound with a self-improve surface.

Anti

self-improve that doesn't read code

Devolves into "summarize the expertise" — claims drift toward what the agent remembers, not what the code is.

Instead

Every claim backed by a re-read file + line.

Anti

Unbounded expertise

File grows past 1000 lines; loading becomes context-polluting; the expert now costs more than it saves.

Instead

Cap at 1000 lines. Enforce in self-improve.

Anti

Single-surface "expert"

One expert.md with no maintenance surface. It's just a command with delusions.

Instead

At least two surfaces — one must maintain.

Anti

Single-use expert

Building the compound for a domain you'll touch once. Amortization never happens; pure overhead.

Instead

Require ≥3 expected interactions per quarter.

The discipline

Expertise is not a document — it is a loop.

Package the domain once as a compound; let the self-improve surface re-anchor every claim to real file paths on every pass. An expert without a maintenance surface is not an expert — it's just yesterday's notes pretending to still be true.