Models and the Cascade

Models and the Cascade

The method uses three models. The fast one reads and reports. The cheap one does the volume. The strong one sees only what the cheap one could not close.

Which model runs which step

Step	Model
Locate the code a draft or spec review needs	fast
Run the gates and paste their output (preflight, holdout, tests, a CI log)	fast
Retro fact collection (lean-stats collect and report, retro-signals.sh)	fast
Spec review of a bigger ticket	cheap
Draft, every tier	cheap
Critic: hunt, then refute	cheap, two fresh agents
First fix round	cheap, the same drafter resumed
A finding not fixed in one round, or an unsure tier 2 answer	strong

The strong model takes the branch and the critic's list. It does not start over.

The fast model never judges code. A gate agent pastes what the script printed, and a pass or fail is whatever the script said. A small model that wrongly refutes a finding drops a real defect with no trace, so the hunter and the refuter stay on the cheap model. Anything a fast agent cannot answer by quoting output goes to the cheap model.

Setting which is which

Setting	Default
LEAN_MODEL_CHEAP	sonnet
LEAN_MODEL_STRONG	opus
LEAN_MODEL_FAST	haiku

All three take a Claude Code model alias: sonnet, opus, haiku or fable. Claude Code resolves an alias to its current model of that name, so the defaults follow new releases without an edit.

To swap them, or to put a different model in a role, set them in the env block of your settings:

{
  "env": {
    "LEAN_MODEL_CHEAP": "haiku",
    "LEAN_MODEL_STRONG": "sonnet"
  }
}

With the defaults, session start prints nothing and the method skill tells the agent the roles. With anything else, mode.py adds a note naming the models and which agents to start on each. Setting the fast model to the strong one adds a warning that the read-and-report agents now cost the most.

Each agent's description carries its role, lean:<role> <owner/repo>#<pr>, so lean-stats can count cost by role. The fast model's roles are search, gate and retro. See Measuring a Batch.

The settings cover the agents a session starts. The session itself runs on whatever /model says.

The other modes

LEAN_AGENTS	LEAN_MODELS	What happens
many	mixed	The method as written. The session starts search, gate and retro agents on the fast model, the drafter and both critic agents on the cheap model, and an escalation agent on the strong one.
many	one	Subagents, all on the session's model. No model override is passed.
one	mixed	One session, and a session cannot change its own model. The fast steps run in the session. The agent says when a step wants the other model. You switch with /model, or it carries on.
one	one	One session, one model. A finding not fixed in one round gets one more round, then goes to you.

Setting both roles to the same model is the same as having no escalation step, and the session-start note says so.

Why the critic does not use the strong model

An earlier version escalated to the strong model only when the automated checks failed. Tested against twelve real defects from one week, that rule would have called the strong model zero times, because every one of the twelve was something the checks had not noticed. So the critic runs on every change the diff gates, on the cheap model, and the strong model is kept for what survives a fix round. README section 8 has the test.

When the critic misses something, the fix is a new scripted check, not a more expensive critic.

What has been measured

Two measurements, both in the README and both from one .NET codebase, on runs from September 2026:

• The cascade as a whole took cost per change from about 13 dollars to about 9, 31% under, at the list prices of 2026-10-02. Before 1.4.0 this said 66 and 25; the cost script counted usage more than once and used old prices. See Measuring a Batch.
• One comparable task used 342 thousand tokens on the cheaper model against 197 to 493 thousand on the expensive one, in 30 minutes against 1 to 8 hours (section 14). The token count barely moved. The saving is in the rate.

Neither was measured on the current defaults. Run Measuring a Batch on your own work before you trust a number.

Cheap drafting stops short

The cheaper model's work was right and it handed back twice without opening the pull request. One line in every brief fixes that:

You are not done until the pull request URL exists. If you hand back without one, the first line of your report says so and names exactly what remains.