context-budget

Context Budget Skill

A context window is a budget that gets re-spent every single turn — everything sitting in it rides every call, which is how a session that "only loaded a few files" ends up paying for them forty times. This skill plans the spend before the session: what earns a permanent seat (loaded once, up front, stable), what gets linked (a map or index, with the full thing fetch-on-demand), and what never enters at all. The quiet second half is cache-awareness: providers price cached prefix tokens at a fraction of fresh ones, but only if the prefix stays byte-identical — so the layout (stable things first, volatile things last) is itself a cost decision.

What This Skill Produces

• The allocation — every candidate piece of context sorted into load / link / fetch-on-demand / exclude, with reasons
• The prefix layout — stable-first ordering that keeps provider caches hitting turn after turn
• The per-turn cost shape — what a turn costs at the start, mid-session, and near the window limit (measure with [token-cost](../token-cost/SKILL.md))
• The eviction rules — pre-decided: what gets summarized, crushed, or dropped when the window fills, and in what order

Required Inputs

Ask for these if not provided:

• The workflow — what the session does, how many turns it typically runs, what it touches (files, APIs, documents)
• The candidate context — everything someone wants loaded: instructions, docs, schemas, examples, history — the raw wishlist the budget disciplines
• The volatility map — which pieces change mid-session (edited files, growing history) and which never do (instructions, schemas) — the cache layout keys off this
• The window and the pricing — the model's context size, and whether the provider prices cached input differently (most majors do — verify the current terms)

Framework: The Budgeting Rules

1. Everything resident rides every turn: the first question for each candidate is not "is it useful?" but "is it useful per turn?" — a 4,000-token style guide consulted once cost 4,000 tokens if fetched on demand, and 4,000 × N turns as a resident. Residency is for what most turns actually use.
2. Link beats load for reference material: an index costs ~3% of its territory ([repo-map](../repo-map/SKILL.md) for code, a crushed schema for data, a table of contents for docs) — load the index, fetch the section when a turn needs it. The escape hatch makes it safe; the ratio makes it policy.
3. Layout is a price decision — stable first, volatile last: cached-prefix pricing (often ~10% of fresh input) only applies while the prefix stays byte-identical, so anything that changes — timestamps, growing history, edited files — belongs after everything that doesn't. One volatile line at position zero un-caches everything below it, every turn.
4. Crush at the gates: tool outputs and files pass through [context-crusher](../context-crusher/SKILL.md) before entering; output rides [token-diet](../token-diet/SKILL.md) levels where the reader allows. The budget's borders are where compression works — inside, the tokens are already spent.
5. Evict by plan, not by panic: decide now what goes first when the window fills — typically: crushed tool outputs (refetchable) → resolved sub-task history (summarized to outcomes via [session-handoff](../session-handoff/SKILL.md)) → stale file snapshots (re-readable) — and never the instructions or the decisions log. Mid-crisis eviction always throws out the wrong thing; that's why the order is written while calm.

Output Format

Context Budget: [workflow] — [window size], ~[N] turns expected

The Allocation

| Piece | Size (~tokens) | Verdict | Why |

|---|---|---|---|

[load / link (with its index) / fetch-on-demand / exclude]

The Prefix Layout

[Ordered: instructions → schemas/standing refs → the maps/indexes → (volatility line) → working state → history — with the cache note per section]

Per-Turn Cost Shape

[Turn 1 / mid-session / near-limit — the arithmetic, cache-adjusted where pricing is known]

Eviction Rules (pre-decided)

[The order, each with its recovery route: "crushed outputs first — refetchable via [command]"]

Quality Checks

• [ ] Every resident piece justified per-turn, not per-session
• [ ] Reference material is linked via an index with a fetch route, not loaded wholesale
• [ ] The layout puts nothing volatile above anything stable
• [ ] Compression happens at the borders (crusher in, diet out)
• [ ] The eviction order exists before the window fills, with recovery routes

Anti-Patterns

• [ ] Do not load what a link can carry — residency is the most expensive real estate in the system
• [ ] Do not put a timestamp at the top of a cached prefix — one volatile byte re-prices everything under it
• [ ] Do not treat the window limit as the budget — the budget is per-turn cost × turns; the limit is just the wall
• [ ] Do not evict the decisions log — history compresses, decisions don't; losing them re-litigates the session
• [ ] Do not design for turn one — sessions are priced by their shape over time, and turn one is the cheapest turn there is