Stop Feeding Agents the Whole Manual

Route first, read small, escalate only on conflict - a practical pattern for keeping AI agents productive across long projects, with a measured case study.

---

The session that burned itself

A while ago, one of my agent sessions did something instructive. It needed to re-index a project in an internal code-intelligence engine - a subsystem it had used successfully many times before. Instead of just doing it, the session went spelunking. It re-read the engine's full 2,140-line instruction manual, cross-checked that against retrieval memory, cross-checked that against a tiered memory system, found minor wording differences between the three, and then spent a serious fraction of its context window untangling which source to trust.

The re-index itself took a few minutes. The debate about how to do the re-index consumed more of the session than the work.

Here is the uncomfortable part. Every fact the agent needed was available, correct, and had been used before. Nothing was missing. The failure was not a knowledge failure and it was not an intelligence failure. It was an admission failure - the session admitted every available source into consideration as if all of them were equally relevant and equally authoritative, and then had to pay the cost of reconciling them.

When I did the post-mortem, the root cause was recorded in exactly those terms. The agent treated available memory and documentation as broadly relevant before classifying the task and routing to the smallest correct source. The fix was not more knowledge. The fix was enforced routing.

This article is about that fix. What the routing stack looks like, why each layer exists, and what happened when I ran a full project close-out under it - with real, verified numbers at the end.

The default failure mode, photographed: everything available, nothing routed.

The failure mode, named

If you run AI agents on long-lived projects, you have probably seen some combination of these behaviors:

Big-doc-first behavior. The agent's default move on encountering any subsystem is to open its largest document. Manuals are written for completeness, not for orientation, so the agent pays thousands of tokens for an answer that lives in three lines.

Memory archaeology. Given access to layered memory - session memory, project memory, retrieval indexes - the agent searches all of them "to be safe," then must reconcile results of different ages and different reliability. Old memory reflecting an earlier state of the system gets weighed against current code, and sometimes wins.

Repeated rediscovery. Every fresh session re-derives the same operational knowledge. How the indexer is invoked, which flags matter, which process must be stopped first. The knowledge exists - in a previous session's transcript, in a handover note, in memory - but nothing forces the new session to find the compact version before it finds the expensive version.

Flat authority. The agent treats a handover note, a memory entry, a design document, and the actual source code as roughly equal sources of truth. They are not. Code is current truth. A handover is a pointer written at a moment in time. Memory is evidence of what was once true. A design doc may predate three refactors. When these disagree - and on a long project they will eventually disagree - an agent without an authority model either picks arbitrarily or burns context reconciling.

None of these are model weaknesses. A stronger model debates the three sources more eloquently. The problem is structural: context admission is unmanaged. The agent loads too much, too broadly, too early, and every loaded source becomes a voice in the room.

The correction: a routing stack

The correction I landed on is a small stack of routing artifacts, applied in a fixed order:

Route first. Read small. Escalate only on conflict.

Concretely, the sequence a session follows when it touches any known subsystem:

1. Orientation layer first. A pointer-and-categorizer layer - I built mine on a pattern called ORBIT - whose job is not to contain knowledge but to say where knowledge lives and what class of source it is. Think of it as a card catalog, not a library.
2. First-contact card second. For each recurring subsystem, a deliberately compact routing card - one page, not one manual - that answers: which mode applies, which surface to use for which need, the three or four hard gotchas, and the authority model. The card exists so the full manual never has to be opened for routine work.
3. Narrow source third. If the card doesn't settle it, read the smallest authoritative source for the specific claim - the one function, the one config file, the one spec section. Not the whole document that contains it.
4. Memory escalation last, and only on conflict. Layered memory and retrieval indexes are consulted when sources genuinely disagree or when continuity context is needed - and what they return is treated as continuity evidence, never as current truth.

The inversion matters. The default agent behavior is memory-and-manuals first, code last. The routed behavior is orientation first, and memory last - because memory is the layer most likely to be stale and the layer most expensive to reconcile.

The routing stack: each step is smaller than the one above it - by design.

The operating stack, layer by layer

The pattern is only as good as the artifacts that enforce it. Here is the stack I run, bottom to top.

ORBIT-style orientation. ORBIT, in my use, is a design pattern for recursive orientation - a layer of pointer records that classify what exists and where authority lives, with an explicit rule that derived summaries carry a source_truth: false marker and can never be promoted into truth. I use it as the pattern for orientation layers and source-truth barriers - a discipline, applied in several artifacts, not a product you install.

A project orientation index. One file per project that answers "where am I, and what do I read first, for which kind of question?" It routes, it does not summarize. The distinction is the whole point - a summary goes stale the day after it is written, while a pointer to the authoritative source stays valid until the source moves.

First-contact cards. The concrete fix for the token-burn session was a one-page card for the code-intelligence engine. Pick the domain, route to the surface, respect four hard gotchas, apply the authority model, keep preflight compact. The card ends with the rule that the full manual is for deep edge cases only. Since that card was installed, routine engine work no longer opens the manual at all. The pattern generalizes - any subsystem an agent touches more than twice deserves a card.

A memory concurrency policy. With multiple memory surfaces (and sometimes multiple concurrent agent sessions), memory needs governance the way shared state always does. Mine states: memory is a tiered bus, not one notebook, classify the domain, ownership zone, and tier before any recall or write, treat recalled content as continuity evidence, not current-state truth, and never write to durable memory without an explicit admission decision - an agent may draft a candidate, a human admits it.

Handover and onboarding notes - demoted, deliberately. Handover documents are essential for continuity and dangerous as truth. My rule is blunt: a handover is a route pointer, not source truth. It tells the next session where to look and what was believed at the time of writing. Every load-bearing claim in a handover gets re-verified against code before it drives a decision. Mid-project, this rule earned its keep. A continuation note compressed a protocol layer down to three protocols, while the implementation and a code-graph query - checked separately - showed four present. The note wasn't lying, it was compressing. Compression plus unearned authority is how errors become durable.

A final evidence capsule. At close-out, one artifact records exactly what is true: commit list, test counts, verification results, residual work, and the boundaries that were held. The capsule is what the next effort routes from - which is what "closure" is actually for. Closure that doesn't produce a recoverable checkpoint is ceremony. Closure that does is infrastructure.

Case study: closing out ChangePlane

ChangePlane is an internal project of mine. A Git-backed control plane for AI-assisted development. It doesn't replace Git - it records, evaluates, seals, and replays the behavior around a code change - the intent, the events, the reasoning-protocol traces, the evaluations, and a tamper-evident seal binding content hashes of all of it. Think of it as provenance for agent work.

At the start of the close-out lane, the project had a working core and four confirmed capability gaps. A capability-router module that was an empty stub, two reasoning protocols (a projection layer and a learning-loop layer) that existed in documentation but not in code, a harness registry with only two of ten specified entity types, and an empty schema directory. A previous session had also just produced the token-burn incident described above - which meant the close-out lane became the first full test of the routing stack.

The lane ran capability by capability, not as one broad "finish everything" push. For each area - read the source specification section for that area (not the whole spec), inspect the current implementation, build to spec-complete, test, adversarially verify with independent reviewer agents, commit. One area, one verified commit, then the next. This is slower per area than a bulk pass and much better at catching drift - several reviewer findings (an unsanitized filename that could have written outside the project's report directory, a CLI that couldn't populate two spec-required fields, stale "planned, not implemented" claims in the docs) were caught by the adversarial review steps and fixed before they could compound.

Three routing decisions during the lane are worth calling out:

Docs were treated as stale until proven current. The project's own protocol documentation still said "planned, not implemented" for features that had already shipped earlier in the build. Because the authority model ranks code above docs, the build read the code first, corrected the docs afterward, and recorded the doc-versus-code divergences explicitly - eight in the main remediation pass, more in a follow-up sweep - rather than silently trusting either side.

The runtime code graph was used as inventory - within its scope. A code-intelligence index gave a before/after picture of the codebase as a graph of entities and relationships. That was invaluable for verifying the gaps closed. But the graph covers code, it proves nothing about Markdown, schemas, or docs coverage. Those were verified by direct file inspection. Domain-scoping the tool prevented a false sense of completeness.

Schemas were built as executable contracts, not decoration. Every record type the system emits got a versioned JSON-Schema file - generated from the live code, not from the (stale) documentation, and validated in the test suite against records actually produced by running the code. Then a layer of negative tests was added - wrong-protocol labels must be rejected, advisory records must reject seal fields, registry records must reject evidence-record fields, and a documentation-flavored record shape that the code never emits must fail validation. Positive tests prove the schema accepts reality, negative tests prove it rejects fiction. That second half is what stops stale-doc shapes from creeping back in. Seal verification got the same adversarial treatment - reviewers modified sealed records after the fact and confirmed verification refuses them, naming the exact hash that broke.

The results - verified numbers only

Everything below comes from the close-out evidence capsule, whose numbers were verified by an independent multi-agent sweep against the project's completion criteria.

• 10 local commits in the close-out lane, each gated on a green test suite, built one capability area at a time.
• 225 tests passing at close-out (up from 134 at the start of the lane).
• 27 versioned JSON-Schema contracts, each validated against real, code-produced records - plus a negative-test battery proving wrong shapes are rejected.
• Code-graph delta: 679 → 861 indexed entities and 2,486 → 3,460 relationships, the router, both new protocol layers, and all ten harness entity types became visible in the code-domain graph - an independent confirmation, from a different tool, that the gaps actually closed.
• Clean tree at close-out, with every one of the project's 17 completion criteria verified with live evidence.
• Boundaries held: the build lane ran local-only - no push, no merge, no deploy, no writes to durable memory (candidates were drafted for human review instead), no secrets recorded anywhere, with the tooling itself enforcing names-only environment capture.

Equally important is what the capsule records as not done: live integration with external evaluation and indexing services remains adapter-level with graceful fallbacks, the seals are tamper-evident, not tamper-proof, several protocol refinements are explicitly future work. Residuals were written down as deliberate scope, not hidden. A close-out that can't name its residuals hasn't closed anything.

The reusable pattern, step by step

You don't need this specific project to use the pattern. Here is the generalized loop.

1. Before the session starts, decide what the agent reads first - and make it small. An orientation index and, for recurring subsystems, a one-page first-contact card. If a subsystem has burned a session twice, write the card before it burns a third.
2. Declare the authority model in writing. A working default: source spec governs requirements, current code governs implementation truth, runtime indexes govern inventory within their domain, handovers and memory govern continuity only. When two layers disagree, the higher one wins and the disagreement gets recorded.
3. Route before reading. Classify the task, pick the layer, read the smallest source that can settle the question. Escalate to bigger documents or memory only when the small source genuinely cannot answer or sources conflict.
4. Work capability by capability. Read the spec section for one area, build it, test it, have something else (a second agent, a reviewer, a checklist) try to break it, commit it. Then move.
5. Make contracts executable. Schemas generated from live code, validated against real outputs, with negative tests that reject the shapes your stale docs would have produced.
6. Verify with an adversary, not a proofreader. Reviewers instructed to refute claims find different bugs than reviewers instructed to check work.
7. Close with a capsule. Exact commits, exact counts, criteria verified, residuals named, boundaries confirmed. If the next session can't restart from it without archaeology, it isn't a checkpoint yet.

A note on the cards, because they carry most of the leverage - a good first-contact card is boring on purpose. Mine follow a fixed shape - when to use this subsystem, which mode or domain applies, a small table routing each need to a surface, the three or four gotchas that have actually burned a session, the authority model, and explicit stop conditions. One page. The discipline is in what you leave out - no history, no rationale essays, no duplicated reference material - those live in the manual the card is protecting you from. Writing one takes half an hour when the pain is fresh, and the payoff compounds. The same card shape now covers my code-intelligence engine, article publishing, and social posting, and each new card was faster to write than the last because the shape was already settled. If a card grows past a page, that is the signal it is trying to become a manual - split the excess back into the underlying docs and leave a pointer in its place.

The authority model: when layers disagree, the higher layer wins - and the disagreement gets recorded.

The AI Agent Context Control Checklist

Two usage notes before the list. First, this is a pre-flight, not a straitjacket - each line exists because it was once a real failure, so skipping one should be a decision, not an accident. Second, it works best embedded where the agent actually starts - a system prompt, a session-start hook, an orientation index - not in a document the agent has to know to go find. The pattern that failed me was knowledge that existed but was never routed to, don't ship the checklist the same way.

A compressed version you can lift into your own agent instructions:

Before the agent starts - orientation index present? First-contact cards for known subsystems? Authority model written down?

Source authority - spec for requirements, code for current truth, docs assumed stale until checked, handover as pointer only.

Memory use - classify before recall, recall narrowly, recalled content is continuity evidence, not truth, writes require explicit admission, drafts otherwise.

Runtime/index use - use indexes for inventory and deltas, state their domain, never let a code graph vouch for docs.

Build loop - one capability at a time, smallest authoritative source, tests green before commit, adversarial review before acceptance.

Verification - independent verification of completion criteria, numbers traced to evidence, residuals named explicitly.

Handover/checkpoint - evidence capsule written, next-session read order stated, boundaries recorded.

Routed, not rationed

It would be easy to misread all of this as an austerity program - give the agent less, spend fewer tokens, hope for the best. That's not the goal, and in practice the routed sessions often do read deeply - full spec sections, entire modules, complete verification transcripts. The difference is that every deep read is a chosen read, reached through classification and routing, instead of a reflex triggered by availability.

There is also a cost asymmetry worth naming. An unnecessary deep read costs twice - once in the tokens it consumes, and again in the reconciliation debt it creates - everything loaded becomes something the agent may now feel obliged to weigh against everything else. A missed deep read, under this pattern, costs almost nothing. The escalation path exists precisely for the case where the small source wasn't enough, and taking it is cheap because the classification step already said where to go next. That asymmetry is the practical argument for defaulting small. The failure mode of reading too little is a quick, guided second read. The failure mode of reading too much is a session spent resolving unnecessary source conflicts.

The goal is not less context. The goal is routed context: the smallest correct source, at the right authority level, at the right time - with escalation as a deliberate act rather than a default. Agents don't fail long projects because they know too little. They fail because nothing tells them what not to read first.

The whole pattern on one card.

Stop feeding agents the whole manual. Hand them the card catalog, and keep the manuals for the day a card sends them there.