Chapter 11 — Context Management

Domain 5: Context Management & Reliability (15%) — task statements 5.1, 5.5

Two settings: long conversations (Scenario 1) and large codebases (Scenarios 2 and 4). One theme: context is a scarce, position-sensitive resource, and the fix is never "get more of it."

1. What progressive summarization destroys

As a conversation grows, systems summarize earlier turns to stay within budget. Summarization is lossy in a predictable way, and the exam tests which things get lost.

🎯 The four categories at risk

Category	Example	Why it's lost
Specific numbers	"$249.00," "order ORD-10023841," "3 units"	Summaries generalize: "the customer discussed a refund"
Percentages	"we agreed to a 30% partial refund"	Same generalization pressure
Dates	"shipped on 14 March," "promised by Friday"	Compressed to "recently" or dropped
Customer-stated expectations	"I was told I'd get free return shipping"	Read as conversational filler, not as a commitment

The last one is the most consequential and the least obvious. A customer's stated expectation is a commitment the agent must honour, and it typically appears once, early, in prose. It is exactly what summarization discards.

🎯 The fix: a persistent "case facts" block outside the summarized history

Maintain a structured block of durable facts that is never summarized and is re-injected on every turn:

=== CASE FACTS (do not summarize) ===
Customer:            CUST-88213 (verified via get_customer, turn 2)
Order:               ORD-10023841, shipped 2026-03-14, $249.00
Issue:               Item arrived damaged; photos provided turn 4
Agreed so far:       30% partial refund ($74.70) offered and accepted, turn 9
Customer expectation: Was told by phone support that return shipping is free
Policy notes:        Order is within the 90-day window (day 47)
=====================================

📎 The properties that make this the right answer:

Structured, so nothing is buried in prose
Outside the summarizable region, so compression can't touch it
Small, so carrying it every turn is cheap
Updated as facts are established, not reconstructed from history

⚠️ The distractor: "increase the context window so summarization isn't needed." It defers the problem rather than solving it, and it doesn't address position effects at all (§2). Another: "summarize less aggressively" — vague, and still loses the same categories, just later.

🎯 Tool results accumulate disproportionately

A tool returning 40 fields when 5 are relevant contributes 8× more context than it needs to — on every call, compounding across a long conversation.

The fix: trim verbose tool outputs before they enter the conversation. Keep the fields the agent actually reasons over. PostToolUse hooks (Chapter 04 §2) are the natural place to do this.

🧠 The pairing to remember: keep the full turn structure, shrink the payloads inside it. Dropping turns loses commitments and causes repeated tool calls. Dropping unused fields costs nothing.

🎯 Pass complete conversation history

Stated positively in the objectives: the model needs the complete conversation to reason about what it has already tried and promised. This is in tension with the previous point, and the resolution is precisely the one above — trim payloads, preserve structure, and pin durable facts outside the compressible region.

2. Position effects — "lost in the middle"

🎯 The phenomenon

Content in the middle of a long context receives less effective attention than content at the beginning or end. This is not a capacity problem — the content is present and readable. It's an attention distribution problem, which is why more capacity doesn't help.

📎 The two named mitigations

1. Key findings first. Put conclusions and the most important material at the start of the content, not buried after supporting detail.

❌ [12 paragraphs of methodology] … [the finding] … [caveats]
✅ FINDING: Revenue declined 8% YoY, driven by the EMEA segment.
   Supporting analysis follows.
   [methodology] [detail] [caveats]

2. Explicit section headers. Headers give the model retrievable structure — an anchor it can attend to — rather than an undifferentiated wall of text.

⚠️ Both are about arrangement, not volume. An option offering "reduce the total content" may be reasonable but isn't the named mitigation; an option offering "use a larger context window" is the standard distractor.

🎯 Upstream agents should return structured data, not verbose reasoning

Applied to multi-agent systems: when a subagent returns three paragraphs of reasoning plus its findings, the coordinator's context fills with reasoning it doesn't need, and the findings end up in the middle of it.

Specify structured returns. {claim, source, date} per finding, not an essay. This is the same instruction from Chapter 03 §1, arriving here for a different reason: there, it was so the coordinator could use the output; here, it's so the coordinator's context doesn't degrade.

3. Large-codebase context

Task statement 5.5. Scenario 4's central problem.

🎯 The diagnostic signal for context degradation

Memorize this symptom, because it's how items signal the condition:

The model begins citing "typical patterns" or generic descriptions instead of the specific classes, functions, and files in the codebase.

That's the tell. When an agent that was previously naming OrderRepository.findByTenant starts saying "typically, a repository class would handle this," its effective grasp of the actual code has degraded. Generic answers are the observable symptom of context degradation.

⚠️ Don't misread the symptom as a knowledge problem or a prompting problem. The fix is contextual.

📎 The four mechanisms

Mechanism	What it does	When
Scratchpad files	Write findings to a file as you go; re-read what you need later	Long exploration where conclusions must outlive the context that produced them
Subagent delegation	Push verbose exploration into an isolated context; get back a summary	Discovery phases (this is the Explore subagent, Chapter 08 §2)
Structured state exports / manifests	Serialize progress to disk so work can resume after a crash or restart	Long-running multi-session tasks
`/compact`	Compress the current conversation in place	Context is filling and you want to continue in the same session

🎯 Scratchpad files

The pattern deserves emphasis because it's counterintuitive: use the filesystem as memory.

As you analyze, maintain notes/codebase-map.md:

## Entry points
- server.ts:42 — express app, mounts /api and /admin routers
- worker.ts:18 — BullMQ consumer for the `orders` queue

## Auth
- src/auth/middleware.ts — validates JWT, sets req.tenant
- Tenant scoping happens HERE, not in the repositories  ← important

## Open questions
- Does the worker path apply tenant scoping? Not yet checked.

Why this beats holding it in context: the notes survive compaction, they're re-readable selectively, they're auditable by a human, and they carry forward across sessions. 🎯 If an item describes an agent that "loses track of earlier findings" during a long codebase task, the scratchpad is the answer.

📎 Structured state exports for crash recovery

Distinct from scratchpads: a manifest captures progress, so an interrupted run resumes rather than restarting.

{
  "task": "migrate 340 components to the new design system",
  "completed": ["Button", "Card", "Modal", "..."],
  "in_progress": "DataTable",
  "blocked": [{"component": "LegacyChart", "reason": "depends on removed d3 v4 API"}],
  "conventions_established": [
    "spacing tokens replace hardcoded px",
    "variant prop replaces the className-based styling"
  ]
}

🎯 The examinable point: the manifest carries decisions, not just a checklist. A resumed run that doesn't know the conventions the earlier run established will produce inconsistent work. Progress alone is insufficient state.

📎 `/compact`

Compresses the conversation in place, in the same session. Right when you want continuity and you're running out of room.

🧠 Compare with Chapter 03 §4's session choices — the exam wants you to distinguish four adjacent options:

Situation	Mechanism
Same session, context filling, history still valid	`/compact`
Coming back to a task, workspace unchanged	`--resume`
Exploring a variant without losing the original	`fork_session`
Old tool results are now stale	Fresh session + structured summary

4. Worked examples

Example 1 — conversation facts

In a customer support agent handling long conversations, agents occasionally offer refund amounts inconsistent with what was agreed earlier, and sometimes fail to honour commitments the customer mentioned receiving from phone support. The system summarizes earlier turns to manage context. What is the most effective approach?

A. Maintain a structured "case facts" block containing verified IDs, agreed amounts, dates, and customer-stated expectations, kept outside the summarized history and re-injected each turn. B. Use a model with a larger context window so summarization is not required. C. Summarize less aggressively, retaining more of each earlier turn. D. Have the agent re-read the full transcript before every response.

Answer and reasoning

The stem names exactly the categories summarization destroys: specific amounts, prior agreements, and customer-stated expectations. A structured facts block outside the compressible region protects precisely those, cheaply, and keeps them positionally prominent.

B — The more context distractor. It postpones the limit and does nothing about position effects; in a long enough conversation the same facts end up buried in the middle.
C — Vague, and loses the same categories later rather than never. It also increases cost on every turn without targeting what matters.
D — If the transcript is being summarized because it doesn't fit, re-reading it isn't available; and if it did fit, you'd be back to lost-in-the-middle.

Reflex applied: pin durable facts outside the summarizable region; don't try to preserve everything.

Example 2 — codebase degradation

During a long refactoring session across a large codebase, an agent that initially referenced specific class and file names begins describing "typical patterns" for the kind of code involved, and its suggestions no longer match the actual implementation. What is the most likely cause and the appropriate response?

A. Context degradation; delegate exploration to subagents and maintain a scratchpad file of established findings. B. Insufficient model capability; enable extended thinking for the remainder of the session. C. The agent needs more detailed instructions about the refactoring goal. D. The codebase is too large for any agent; split the refactor across separate repositories.