What We Load Before We Read Anything Else

Every repo in the fleet runs on the same process document. Most of it is unremarkable. It tells agents to answer questions fully, to review generated documents before trusting them, to explain why a change is wanted rather than saying "fix this." Those are the parts we could have written for a human team. The section we return to most often is the one that would make no sense for a human team at all: the rules for what to load into context, in what order, and when to throw it away.

This essay is about that section. We want to lay out what the rules say, why we think they are shaped the way they are, and where they still feel provisional.

The loading order

The process document, in its v0.19.0 revision, gives a five-row priority table for context loading. The first row is the repo's NOTES.md, marked "Always at session start," with a full read. The second is the current sprint files, read fully when implementing or reviewing. The third is the product and design documents, loaded by targeted search rather than in full. Fourth is source code, retrieved just in time for the feature being built. Fifth is test files, retrieved just in time when writing or reviewing tests.

The ordering encodes a claim about where the useful information lives. NOTES.md sits at the top not because it is the most authoritative file but because it is the file most likely to be stale if nobody reads it. It is where the previous session left its state. If an agent skips it, the agent starts over, and the repo pays for that twice: once in wasted work, once in the drift between what the notes say and what the code now does.

Source code sitting at fourth surprises people. The intuition from human onboarding is that you read the code first. But a model reading code it does not yet need is spending tokens on material it will have to reload later anyway, once it knows which part matters. Anthropic's own guidance on context engineering for agents makes the same argument from the model side: context is a finite resource with diminishing returns, and the job is to find the smallest set of high-signal tokens that gets the task done. The priority table is our operational version of that.

Grep versus skim

The document draws a line between two ways of touching a file. Grep is for finding a specific function or class definition, locating an error message or constant, finding all usages of a symbol, or checking a pattern across files. Skim, meaning an actual read, is for understanding structure and flow, reviewing architecture, getting the context around a function, or initial orientation in an unfamiliar codebase.

We find this distinction does more work than it looks like it should. The failure mode it prevents is not laziness but the opposite: an agent that reads too much because reading feels thorough. A read of a large file to answer a question a single ripgrep call could have answered costs the same tokens as a read that was actually needed, and those tokens do not come back.

The same logic governs when to request a directory tree. The document says to ask for one the first time a directory is explored, when looking for test file locations, when understanding module organization, or before a major refactor. It says not to ask when the path is already known, when the directory is small and already seen, or when a single grep would do. None of these are hard rules an agent could enforce mechanically. They are judgment calls, and the document is honest about that by phrasing them as guidance rather than gates.

The budget zones

The part of the section we quote most often is the context budget table. Three zones: green under 5000 active tokens, yellow from 5000 to 10000, red above 10000. Green means continue. Yellow means consider summarizing and clearing tool results. Red means run a checkpoint and archive to NOTES.md.

A window left open in a room no one is using.

We should be careful about what these numbers are. They are thresholds the process document sets for its own agents. They are not measurements of anything, and they are not claims about model capability. The Claude context window is documented separately and is far larger than any of these figures. The zones are about attention, not capacity. An agent carrying ten thousand tokens of raw grep output is not out of room. It is out of focus, and the process document treats that as the earlier and more important limit.

The remedy the document prescribes for heavy operations is a three-step loop. Extract the key information into structured notes. Summarize by replacing the raw output with a single line. Clear, meaning let the raw data decay from active context. The example given is a grep result of roughly 500 tokens collapsed to about 30: a count of references, a count of files, and two file-and-line locations that matter. We have found the discipline of writing that one line is where the actual understanding happens. An agent that can compress the output has read it. An agent that cannot has only looked at it.

Handing a session off

The last part of the section addresses work that does not fit in one session. The handoff protocol has three steps. Update NOTES.md with the current focus, the split between completed and remaining items, and any blockers or decisions needed. Create a checkpoint block with a fixed shape: last working state, what it is blocked by, and which files were modified. Commit partial work with a WIP prefix, or stash it with a description.

The example checkpoint in the document is deliberately small. A task name, a progress count of three subtasks done out of five, a file and line number for where the cursor was, a single next action, one open decision on rate limit values, and three modified files with a one-word status each. Everything a fresh session needs to resume, nothing it would have to skim past.

We lean on the git stash and WIP commit conventions more than the document's brevity suggests. When a session ends mid-task, the working tree is the only artifact that cannot be reconstructed from notes. The notes tell the next agent what was intended. The tree tells it what was actually done. Both have to survive.

What we are less sure about

The zone thresholds are the most contested numbers in the document. They were set for a particular revision of the tooling and a particular pattern of tool output. We do not have evidence that the boundaries are in the right place, only that having boundaries at all changed behavior. An agent that knows there is a red zone checkpoints more often than one that does not, regardless of where the line sits. That may be the whole effect.

The other soft spot is the instruction that NOTES.md is read fully at session start. As a repo ages, that file grows, and a full read of a long notes file is exactly the kind of low-signal loading the rest of the section warns against. The document does not yet say when to prune NOTES.md or how. That is a gap, and we are noting it here rather than pretending the process is finished.

What the section gets right, we think, is its premise. Context is the scarce input. Everything else in the fleet's process follows from deciding to treat it that way.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-09-08: enrich what-we-load-before-we-read-anything-else: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 6671