Chapter 5: Context Routing¶
Choosing What the Agent Reads¶
1. Context Is Finite and Costly¶
Every AI-assisted change begins with a retrieval step. Before an agent writes a line, it reads files โ and those files become the evidence it reasons from, the constraints it enforces and the patterns it follows.
That reader's window is finite. Every file loaded competes for attention with every other file, and every token spent on noise is a token not spent on reasoning. Context economy is the name for the discipline that follows: context is a finite resource, managed deliberately. It is not a retrieval optimisation. It is a first-class architectural concern: decided once, and binding on every task of that type. A task is one piece of work an agent is asked to do. A task type is a category of tasks that share the same context requirements.
Two failures follow from ignoring it, and both are paid at review.
Loading too much. Forty files arrive, most of them irrelevant. The one that matters competes with the other thirty-nine, cost rises, precision falls โ and the failure looks like confusion rather than omission. The agent produces a plausible change that violates a constraint in a file it never loaded.
Loading too little. Nothing arrives by default, so the agent asks, or guesses. A guess looks correct and is built on incomplete evidence, which is the failure this chapter exists to remove.
Both have the same root cause: nobody decided what to load. The three structures are in place and the repository holds them, but nothing says which part of them a given task needs.
That decision is context routing: for each task type, a named list of what the agent reads โ declared where the policy lives, mapped where the context lives, and verified in the record of what was actually read. Without routing, context economy is a principle. With it, the window becomes a measurable property of every task. What it costs to fill that window โ and how to bound the spend โ is the economy chapter's subject; this one decides what may enter.
๐ฐ Cost Check: context is the one budget that cannot be seen on a bill. Loading everything costs tokens on every run and precision on every review; loading nothing costs a wrong change and the afternoon spent finding it. The only place the cost is bounded is where the decision is made explicit.
๐ฏ What You'll Learn¶
- Why context is finite and costly โ the principle that makes routing necessary
- Context routing as a mechanism โ the deliberate, rule-based composition of the context window for each task type
- Load units as the abstraction โ how to organise context by what a task needs, not by what the codebase contains
- Verification as the proof โ how to measure whether routing is working, not just whether it exists
โ What to Check¶
- For your three most common task types, name the files an agent should read. If the answer is "it depends", you have found the routing gap.
- Count the times an agent read a file the task never needed. That is the cost of loading too much.
- Count the times an agent produced a plausible change that violated a constraint in a file it never read. That is the cost of loading too little.
2. Load Units: Organising Context by Task Need¶
What a Load Unit Is¶
A task type is a kind of work that recurs โ changing a migration, adding an endpoint, rotating a credential. A load unit is the set of files one task type needs, named once. It is not a folder and not a file โ it is a list that crosses the repository: the contract, the service it describes, the policy that constrains it, the runbook for when it fails.
Three properties make it a unit rather than a wish:
| Property | The test |
|---|---|
| named | the files are listed, not described |
| bounded | the list has a number, and a run can exceed it |
| stable | the same task type reads the same files on Tuesday as on Monday |
The unit is sized by the task, not by the directory tree. One task may span three folders and four hundred lines; another may be twenty files in one place. If a unit names more than about ten files, it is a folder in disguise โ the task is probably two tasks, or the unit is the wrong unit.
flowchart LR
T["task"] --> R{"routing table"}
R -->|"names a load unit"| L["the files that task needs"]
R -->|"no match"| F["an agent that infers<br/>from whatever it can see"]
L --> W["a change written from evidence"]
What this shows: the routing table is the only thing standing between a task and an inference.
โ What to Check¶
- For your three most common task types, name the files an agent should read. If the answer is "it depends", you have found the routing gap.
- Take one of those units and count its files. If the number is above ten, the unit is a folder in disguise.
3. The Map Is a Fact Document¶
The Map answers where things are and what they are for. It does not state rules โ those are the Law's job โ and it does not restate the Playbook. A Map that starts carrying rules becomes a second source of truth, and the two will disagree within a month.
The Map is organised in load units (ยง2): each section names the files one task type reads, so a reader who knows the task type knows where to start.
| Map (a load unit) | Not a Map |
|---|---|
| "changing a migration: read the schema contract, the migration gate, the rollback runbook" | "the database is important" |
| a pointer to the file that owns the rule | the rule, restated |
The pointer problem. No harness auto-loads the Map. Something must tell the agent to read it โ a sentence in the Law, a routing row, an instruction in the harness. A Map nobody is told to open is a document, not a route.
The pointer, as a line โ one sentence in the Law, before anything else it says:
## Before your first change
Read `AI_CONTEXT.md`. It names where things are; this file names what must be true.
Without that line the routing table has no entry point. An agent that never learns the Map exists reasons from whatever it can see, which is the loading too little failure with a confession attached.
โ What to Check¶
- Does the Map state any rule? Move it to the Law.
- Is there a sentence, anywhere, that tells an agent to read the Map before working? If not, nothing routes.
4. The Routing Table Is a Rule¶
A routing table is a rule in the Law: before a task of type X, read these units. Not a suggestion, not a diagram โ a row an agent can follow and a check can verify.
| Task type | Load units | Budget |
|---|---|---|
| change a migration | schema contract ยท migration gate ยท rollback runbook | 3 files |
| add an endpoint | API contract ยท the feature's folder ยท the auth policy | 4 files |
| change a workflow | the workflow's definition ยท its gate ยท the evidence pack | 3 files |
| rotate a credential | the secrets policy ยท the consumer inventory ยท the rotation runbook | 3 files |
The budget is a ceiling a run can exceed: three files means three, not about three. A row that is routinely exceeded is saying something โ either the unit is too big or the task type is really two task types.
โ What to Check¶
- Every routing row names concrete files, not a directory.
- The budget is a number you could exceed visibly.
5. Verification โ What Was Actually Read¶
The execution log records files-read. Compare it with the routing table: what the table said to load, and what the run actually opened.
A mismatch is a finding, not a footnote:
| Observation | What it means |
|---|---|
| read fewer than the row names | the row is too big, or the run skipped a file it was told to read |
| read more than the row names | the row is missing a file the task needs, or the agent read beyond its route |
| read nothing the row names | the route is not being followed at all |
The point is not to catch the agent. It is that the routing table is only true if the run shows it was followed โ otherwise the table is a claim about intent, and the agent's behaviour is the fact.
One run, in the shape the log produces:
task: change a migration
route: contracts/schema.md ยท docs/migration-gate.md ยท runbooks/rollback.md (budget 3)
files-read: contracts/schema.md ยท docs/migration-gate.md (2 of 3)
finding: the rollback runbook was never read
That is the shape of a useful finding: a named delta, and a question with two possible answers. Either the row was wrong, or the run did not follow it. Here the row was right, so the run is the thing to fix.
โ What to Check¶
- Take one run. List the files it read. Compare with the routing row for that task type. Name the delta.
- Does anything fail when the delta is large? If not, the routing table is a wish.
6. Failure Modes¶
Beyond loading too much or too little, three failure modes are specific to routing:
- Stale routing. The Map names a file that moved; the agent reads nothing and infers.
- Routing in plugin configuration. A rule that lives in the harness's config cannot be reviewed, diffed or tested โ and disappears when the tool changes.
- A Map that became a second Law. Two rule sources; two answers; a review that cannot say which is authoritative.
The pattern repeats: the rule must live where it is reviewed, and the effect must be observable.
7. Build the Routing Table¶
Artefacts¶
| Artefact | What it is for | Where it lives |
|---|---|---|
| Map | where things are, as load units | docs/map.md (or the repo's context file) |
| routing table | task type โ load units โ budget | the Law, as a rule |
| budget | one number per row, a ceiling a run can exceed | beside the routing table |
| conformance check | routing compared to files-read |
the gate or the nightly audit |
The Map skeleton, as a shape โ sections are load units, each one a task type:
# Map โ where things are
## changing a migration
read: contracts/schema.md ยท docs/migration-gate.md ยท runbooks/rollback.md
## adding an endpoint
read: contracts/api.md ยท services/<name>/ ยท policies/auth.md
The routing table, as a shape โ a rule, with a number you can exceed:
# routing table (in the Law)
routing:
- task: "change a migration"
load: ["contracts/schema.md", "docs/migration-gate.md", "runbooks/rollback.md"]
budget: 3
Decisions¶
| Choice | Default | What changes if you choose otherwise |
|---|---|---|
| organise the Map by | task type (load units) | a codebase index, which no task can use |
| where the routing rule lives | the Law, reviewed | plugin config, unreviewable and unportable |
| the budget | a number per task type | "read what you need", which is not checkable |
| verification | files-read compared to the row |
routing that is asserted and never observed |
โ Checks¶
- Every routing row names files and a number.
- A run's
files-readcompared to its row is within the budget or reported. - No rule lives only in harness configuration.
Sequence¶
- Write the Map as load units for your most common tasks. Checkpoint: each unit names files, not folders.
- Move the routing into the Law as a table. Checkpoint: a row can be followed without reading anything else.
- Set the budgets. Checkpoint: the number is one a run can exceed.
- Add the comparison to the log or the nightly audit. Checkpoint: a run outside its budget is reported.
Done When¶
- An agent can be routed to a task type by one sentence in the Law.
- A run's reads can be compared with the route, and the delta is visible.
- No rule about routing lives in tool configuration.
8. ๐ Chapter Summary¶
Routing is the decision that turns a repository into context.
- Context is a routing decision, not a dumping problem โ and both "load everything" and "load nothing" are failures.
- The Map is a fact document organised in load units; rules belong in the Law.
- The routing table is a rule โ task type, files, budget โ and a budget a run can exceed.
- Verification is the point: compare
files-readwith the route; a mismatch is a finding. - Failure modes are familiar: load-everything, stale routing, routing hidden in tool config, a Map that became a second Law.