Context Budget

Context budget

The context window is RAM, not a hard drive. Full ≠ free: a window stuffed to 95% does not just cost more money, it reasons worse. Model performance degrades as input tokens grow — even well inside the stated limit, every token added depletes a finite attention budget (Chroma "Context Rot" research, accessed 2026-06-02). Your job on a long task is to keep the live window lean and externalise everything else, so the work can run for hours across many fresh windows without losing the thread.

The one rule: if you can reconstruct a thing from a file or from git, it does not belong resident in the window. Keep load-bearing-right-now; evict the rest. The cost of forgetting is one re-read; the cost of hoarding is silent quality rot on every turn that follows.

Neighbours, so you don't do their job here: pricing tokens, spend ledgers and hard $ caps are ../cost-tracking/SKILL.md — same words ("token budget"), different unit, dollars vs. attention. Finding the right context via embeddings/chunking is ../rag/SKILL.md; RAG is how you find context, this is how much you let live and when to evict. Prompt text, few-shot and output format are ../prompt-engineering/SKILL.md; the agent loop, tool schemas and provider adapters are ../building-agents/SKILL.md; partition-then-gather fan-out of independent work is ../parallel/SKILL.md (this skill uses subagents as a context-isolation tactic but does not own that discipline); the 01-TOOLS / 02-DOCS control plane is ../harness/SKILL.md.

Read the gauge first

Before you do anything, estimate utilisation: live input tokens ÷ the model's window limit. You cannot manage a budget you are not watching.

• Compact early — around ~60% utilisation, not 80–95%. Most people only act when quality already broke at 80–95%; by then the rot already happened. Treat 60% as the line where you start reducing, not panicking (practitioner guidance on Claude Code /compact, accessed 2026-06-02).
• Trust the symptoms as an earlier trigger than the number. You can feel rot before the gauge confirms it:
  • You re-read a file you already read this session.
  • You restate the plan or a decision you already made.
  • You contradict an earlier choice.
  • Tool results from ten turns ago are still sitting verbatim in the window.

Any one of those is a signal to act now, regardless of the percentage.

The four moves

Every context-engineering action is one of four moves (context-engineering surveys, accessed 2026-06-02). Pick by what is eating the window.

1. Offload — summarise a tool output or large read; store the full thing in a file or reference, keep only the distilled fact + a path. Why: raw bytes you might need later don't have to be resident now.

Bad:  <pastes the entire 4,000-line config file into the window to "have it">
Good: read it, keep the 30 relevant lines, leave a note:
      "full config at src/app/config.ts:1-4012; the load-bearing keys are X, Y, Z (lines 88-120)"

2. Reduce — compact or summarise stale history so the window carries the conclusions, not the journey. Why: the dead-end exploration that got you to a decision is not the decision.

Bad:  carry 2,000 lines of trial-and-error debugging transcript forward unchanged.
Good: compact to "tried A (failed: race condition), B (failed: types); C works — see commit a1b2c3d."

3. Retrieve — fetch a fact at runtime instead of pre-loading it. Why: most of what you might need, you won't; pull it when you actually need it. This is RAG's job — see ../rag/SKILL.md.

Bad:  load all 40 design-doc sections up front in case one is relevant.
Good: keep an index; fetch section 7 the moment the task touches auth.

4. Isolate — hand a read-heavy or independent subtask to a subagent with its own fresh window; take back only the answer. Why: a big read in a child window never pollutes the parent's. Subagents are the single most effective anti-rot pattern (Anthropic context-engineering guidance, accessed 2026-06-02).

Bad:  read 12 files into the main window to answer "which module owns retries?"
Good: spawn a subagent to scan them; it returns "retries live in lib/http/retry.ts:44" — that one line lands in the parent.

Decision table: the window is filling — what do I do?