A Mental Model is a dense YAML briefing for one domain — read at task start so agents orient in seconds instead of minutes. Self-improved after changes. Capped at 1000 lines.

Primitive

Mental Model

Why it exists

Cold-start rediscovery vs warm-start briefing.

no mental model

🤖 Agent rediscovers the domain every session

s1grep, read, infer, ask~15k ctx

s2grep, read, infer, ask~15k ctx

s3grep, read, infer, ask~15k ctx

s4grep, read, infer, ask~15k ctx

Onboarding cost is paid every time. N sessions × rediscovery cost = stateless amnesia.

with mental model

🤖 Agent reads one YAML and starts working

s1read expertise.yaml → work~1k ctx

s2read expertise.yaml → work~1k ctx

s3read expertise.yaml → work~1k ctx

s4read expertise.yaml → work~1k ctx

Onboarding amortizes to zero. Specialization compounds session-over-session instead of resetting.

First, what it isn't

Four knowledge primitives. Different jobs.

Mental Modelthis node

YAML, 10 sections, 1000-line cap

Self-improve after code changes

Curated briefing, read before work

Skill Pack

SKILL.md + resources dir

When domain evolves

On-demand knowledge, auto-loaded

Conversation Log

JSONL, append-only

Every turn (automatic)

In-session coherence

Context Bundle

JSONL tool-call capture

Every tool call (automatic)

Cross-session warm-start replay

The Mental Model is structured, curated, per-domain, intentionally small. That's what separates it from the neighbors.

Anatomy

Ten sections. In this order.

.claude/commands/experts/auth/expertise.yaml

≤ 1000 lines

01overview

What the domain does, owns, depends on, and feeds.

02core_implementation

Files, line numbers, class and function signatures.

03patterns

Recurring designs with example file+lines and anti-patterns.

04data_structures

Input/output models, schemas, typed fields that flow through.

05configuration

Env vars, defaults, config files, required-vs-optional.

06key_operations

Common operations: function path, inputs, returns, caveats.

07error_handling

Exception patterns, retry rules, what callers must handle.

08testing

Test file, run command, coverage, known gaps.

09best_practices

Hard rules. Imperative statements. Violations cause bugs.

10known_issues

What's wrong now: severity, impact, workaround, proper fix.

Skip a section if the domain genuinely lacks it. Never pad with TODO placeholders — readers can't tell what's missing vs what doesn't apply.

The fill rule

Every claim backed by a file actually read.

Summarizedcredibility collapses on first mismatch

pattern:

"uses the session pattern"

Useless. Which file? Which function? The agent still has to grep. If the claim is wrong, the agent has no way to know before shipping.

Citedverifiable, self-improvable

file: apps/orchestrator/session.py

line: 45

symbol: SessionManager.get_or_create

behavior: returns existing or spins new

Anchored. If the function moves, self-improve catches the drift. The claim is either verified or it's gone.

The maintenance loop

Without it, the Mental Model decays faster than it compounds.

Run after any significant domain change.

01

Detect drift

scope via git diff

→

02

Re-read files

compare to current

→

03

Update claims

fix lines, sigs, shapes

→

04

Enforce budget

trim if > 1000

→

05

Parse-check

valid YAML or reject

Without self-improve, the Mental Model is a one-time snapshot that decays.

The first time an agent hits a stale claim, the whole file's credibility collapses.

The sweet spot

Line budget is context budget.

Mental Model size

context budget vs domain coverage

1000 (cap)

STARVE

✓ SWEET SPOT

POLLUTE

0~15010001500+

Below the sweet spot: agent lacks the knowledge it needs.

Above the cap: loading the model consumes the context it was meant to save.

The create/don't-create test

All three conditions, or don't bother.

create when ALL three

Mental Model earns its keep

• Domain is complex — one-shot prompts don't produce reliable output
• Domain evolves — static expertise goes stale, justifies self-improve
• Touched ≥ 3× per quarter — amortizes the fill cost

skip when any

Mental Model is overhead

• Domain is static — write a one-time doc instead
• Domain is trivial — one-shot prompt handles it fine
• Domain is touched once — fill cost exceeds benefit
• You don't have your own mental model yet — you can't evaluate the expert

The discipline

Agents forget. The Mental Model is what remembers for them.

Dense, cited, structured, capped, self-improved. The inversion of conversation-history bloat: grow only by conclusions worth keeping, with a hard budget. Specialization compounds instead of resetting.