When Context Goes Wrong
Context engineering has its own canonical bug list. Learn to recognize each failure by its symptom - and apply the right fix
Symptoms, Not Mysteries
When an agent misbehaves, beginners blame the model and reach for a bigger one. Usually the real cause is one of a handful of context failures with recognizable symptoms. Learn the list and you'll diagnose problems in seconds instead of guessing.
The Three "Too Much" Failures
Symptom: the agent gets slower, pricier, and somehow less accurate as you give it more. Cause: you dumped everything in "to be safe" and hit context rot. Fix: retrieve less but better - re-rank to a tight top-k.
Symptom: the agent fixates on something irrelevant that happened to be in the window. Cause: loud but off-topic material crowds out the signal. Fix: cut the irrelevant chunks; enforce a relevance threshold.
Symptom: the agent contradicts itself or wavers. Cause: the context contains conflicting signals pulling it different ways (two docs that disagree, an old rule and a new one). Fix: remove the stale/contradictory source; don't make the model referee a fight you can settle.
Stale Retrieval
Symptom: the agent confidently uses something that's no longer true - calls a function that was deleted, quotes an old policy, references last quarter's number.
Fix: track freshness. Refresh indexes when sources change, or lean on just-in-time retrieval that reads the current file instead of a months-old snapshot. This is especially nasty for code, where stale info compiles and runs before it fails.
Lost in the Middle (Again)
Symptom: the crucial fact was in the context, but the agent acted like it never saw it. Cause: it was buried in the middle of a long block (Lesson 66). Fix: reorder - put the highest-signal material at the top or bottom - and shrink the block so there's less middle to get lost in.
Quick diagnosis: "The info was there but ignored" → lost in the middle (reorder) "It used outdated info" → stale retrieval (refresh) "It fixated on the wrong thing" → distraction (cut noise) "It contradicted itself" → confusion (remove conflicts) "Slow, costly, and worse" → overload (re-rank, trim)
The Boring-but-Real One: Cost & Latency
Not every failure is a wrong answer. Sometimes the agent is right but too expensive or too slow to be worth it. Every extra retrieval, tool call, and re-rank shows up in the bill and the wait time. An agent that quietly uses 5× the context it needs is a real failure even when its answers are fine.
The Whole Level in One Checklist
- Instructions at the right altitude - not brittle, not vague? (Lesson 67)
- Retrieval targeted and fresh - not a dump, not stale? (Lesson 68)
- Memory managed - compaction / notes / sub-agents for long tasks? (Lesson 69)
- Tools few, clear, and non-overlapping? (Lesson 70)
- A re-ranker enforcing a tight top-k, highest-signal at top/bottom? (Lesson 71)
- A token budget tracked per task, with alerts? (Lessons 71, 72)
Hands-On: Diagnose From Symptoms
Slower, costlier, less accurate as you add context - fix by retrieving less but better (re-rank)
Agent fixates on irrelevant material in the window - cut the noise, enforce a relevance threshold
Conflicting signals make the agent waver - remove the stale or contradictory source
Confidently uses outdated info from an old index - track freshness or read current files just-in-time
Info was present but ignored because it was buried - reorder to top/bottom and shrink the block
Right answer, too slow/expensive - set per-task token budgets and alert on overruns
Almost every context bug is solved by better-targeted context, not more context