Progressive Disclosure

Progressive disclosure is the discipline of keeping a short index resident in context and loading full content only at the moment of need. You've already met it twice without the name: skills keep a description resident and load the body on demand (lesson 14); MCP keeps tool descriptions resident while servers hold the machinery (lesson 7). It's also the most misapplied advice in agentic work, because the popular version — "lazy-load everything" — is wrong for about a third of your content, and the correct answer is a small calculation, not a slogan. This lesson is the calculation, the failure nobody warns you about, and the judgement calls that come up weekly.

The actual trade

Keeping a thing resident costs its full size, every turn, used or not (lesson 2's desk rent). Deferring it costs three things people forget to add up: the index line every turn regardless, plus the body on the turns it loads, plus a round trip to fetch it — and, if you assemble API requests yourself, a potential cache penalty (lesson 12: material injected above stable content snaps the prefix; late-loads belong at the tail or the "saving" is a 5x cost).

So deferral is a bet about frequency. For a body of B tokens with an index of I tokens, needed on fraction p of turns, deferral wins roughly when:

I + p × (B + round-trip)  <  B

You'll never compute this precisely and never need to — its shape makes every decision:

• Big and cold defers. A 3,000-token reference needed once a week is the perfect deferral: tiny index, body almost never paid.
• Small and hot stays. A 40-token rule used most turns should never be deferred — the index approaches the body's size and you've added a fetch to achieve negative savings. This is the case the "lazy-load everything" slogan gets wrong.
• The middle needs an estimate of p — not a precise one. "Most turns / sometimes / rarely" is enough resolution to sort everything you have into the three mechanisms you already own:

Frequency	Home	Lesson
most turns	resident (CLAUDE.md core)	8
situational	skill (triggered)	14
on request	command / doc pointer	9

That table is this lesson's punchline: you don't need new machinery for progressive disclosure — you need the sorting rule for the machinery you have.

The failure nobody warns you about: the index grows

Every deferred item adds a resident index line. Defer enough things — dozens of skills, hundreds of tools across connected MCP servers — and the catalog itself becomes the context hog: several hundred "cheap" description lines is tens of thousands of resident tokens, paid every turn, describing content that mostly never loads. The trap has a nasty property: no individual decision was wrong. Each item, evaluated alone, correctly chose deferral. The sum is still overgrown — and it creeps, because items get added one at a time and nothing ever prunes.

Countermeasures, in escalating order:

1. Treat the index as a budget line. Know roughly what your resident descriptions cost (lesson 2's fixed-overhead audit includes them). When the catalog rivals your working context, it's overgrown — no further analysis needed.
2. Prune on inactivity. The skill that hasn't fired in months, the server connected "just in case" (lesson 7): disconnect. Reconnecting is a command; carrying it is a tax on every turn forever.
3. At real scale, disclose the index itself. Group tools and skills into families: a one-line family entry stays resident; members load when the family becomes relevant. Two-level disclosure is how genuinely large surfaces stay affordable — it's the same break-even arithmetic, applied recursively.

Judgement calls that come up weekly

Never defer safety. Invariants and prohibitions must be resident — a rule that loads after the model needed it is a rule that failed, retroactively. If it's on lesson 15's list (or ought to be), it rides every turn, and its cost is simply the price of correctness. Deferral is for knowledge, never for law.

Defer for breadth, stay resident for depth. A session that might touch any of forty domains — support triage, monorepo work — is disclosure's home turf: the per-session relevant fraction is tiny. A session guaranteed to live all day in one domain should load that domain up front; deferring it adds round trips to a certainty.

An index line can be too good at being small. The description is what the model decides from (lesson 14): compress it too far and you've hidden the body from the very trigger that's supposed to fetch it — the silent-miss failure, self-inflicted. The index must stay a faithful advertisement, not just a short one.

Judge changes on spend and outcome, never on context size. Deferral reliably shrinks average context — the metric everyone watches — while sometimes raising cost (cache breakage, hot items deferred) or degrading quality (the model can't want what it doesn't know exists). A smaller desk is not the goal. A cheaper, better session is, and only measuring both (lesson 21 gives you the instrument) tells you which one you got.

The compact summary

Residency is a rent decision. Charge every piece of content rent proportional to its size; ask how often it actually shows up for work; house it accordingly — always-on, triggered, or fetched. And remember the two clauses that separate the professionals from the slogan: the directory in the lobby pays rent too, and the fire code is not a candidate for the basement.