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?

What is eating the window	Move	Concrete action
Bloated tool output / a giant pasted file or log	Offload	Distil to the load-bearing lines, write the full thing to a file, keep a path:line note.
Stale early history, dead-end exploration	Reduce	/compact now (you're at ~60%, not 95%) with preserve instructions; keep decisions, drop the journey.
A fact you need is simply not in the window	Retrieve	Fetch it on demand via ../rag/SKILL.md; don't pre-load "just in case".
A read-heavy or independent subtask	Isolate	Spawn a subagent (fresh window) via ../parallel/SKILL.md; take back only the answer, never the transcript.
The whole task won't fit any single window	Hand off	Write a progress file (below) so a fresh window resumes in one read.

Compaction, concretely

Manual (/compact). Do it early and tell it what to keep. A bare /compact will happily drop the file paths and decisions you needed.

/compact keep: the migration plan, every file path touched, the three decisions
(use Drizzle, keep the legacy table read-only, cut over Friday), and the open TODOs.
drop: the exploratory diffs and the debugging transcript.

Server-side (beta). The API can compact for you: beta header compact-2026-01-12, edit type compact_20260112, default trigger at input_tokens = 150,000 (min 50,000), pause_after_compaction defaults false. The API drops all blocks before the compaction block and continues from the <summary> — and you must append the whole response (including the compaction block) to subsequent requests (Claude API "Compaction" docs, accessed 2026-06-02). The exact contract and the append rule are version-specific and rot fastest, so they live in references/handoff-and-compaction.md — read it before you wire this up.

A good summary preserves decisions, file paths, open TODOs, and gotchas/constraints. A good summary drops raw logs, dead-end exploration, and redundant restatements. If the summary can't resume the task, it failed.

Surviving a fresh window (handoff discipline)

When the task is bigger than one window, the win is making a fresh window resume the work in a single read. The long-running harness pattern (Anthropic, "Effective harnesses for long-running agents", published 2025-11-26, accessed 2026-06-02) is: an initializer session sets up the work, then each coding session works one unit at a time and leaves a structured update — a progress log (e.g. claude-progress.txt) plus git history plus a structured feature list — so the next window reconstructs state without you re-explaining it.

Write the handoff before you run out of room, not after quality already cratered. The template (Goal / Done / In-progress / Next / Gotchas / Key paths) and a good-vs-bad summary checklist are in references/handoff-and-compaction.md.

Budget allocation heuristic

A starting split for a production agent's window — a heuristic, not a law (context-engineering production guidance, accessed 2026-06-02). Tune to your task; the point is to leave headroom and trigger reduction well before 100%.

Slice	Rough share
System / instructions	~10–15%
Tool definitions & results	~15–20%
Knowledge / RAG injections	~30–40%
Working headroom (kept clear)	the rest — defend it

Anti-patterns

Anti-pattern	Why it rots	Do instead
Read the whole repo into context "to be safe"	Thousands of irrelevant tokens degrade every later turn	Read the files the task touches; leave path notes for the rest
Compact only at 95% when things break	The rot already happened; you're summarising damaged reasoning	Compact at ~60%, before quality drops
Let tool results pile up verbatim	Stale outputs from 10 turns ago still taxing attention	Offload to a file, keep the distilled fact + path
Re-explain the plan every turn	Burns the same tokens repeatedly and invites drift	State it once; keep it in the progress file, reference it
Paste a subagent's full transcript back into the parent	Defeats the entire point of isolation — the child's bloat lands in the parent	Take back only the answer/artifact, never the transcript
Treat the window as infinite because the model "has 1M"	Context rot scales with tokens regardless of the limit	Budget against attention, not the advertised ceiling
Carry dead-end exploration forward	The journey isn't the decision; it's pure noise	Reduce to the conclusion + the commit that proves it