> What earns its place in a context file — from The Handover, the-handover.org/docs/what-earns-its-place > Authors: Leon Mallett (captivated.online) with Claude Code · Last confirmed working: 2026-09-16 on Claude Code 2026-09 > © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence > Position — The Handover's own view, stated in full. Not independently vetted. There is a tension in every context file, and most of them resolve it by ignoring it. You want an agent to work in a way that is correct for this project — compliant, in-house, aware of constraints it cannot see. The mechanism for that is written context. But written context is loaded on every session, costs tokens every time, and competes for attention with the task. **The mechanism for making an agent better is also a mechanism for making it worse**, and nothing about writing a good document tells you which you have produced. ## Two tests, and both have to fail before something is waste A passage earns its place if it changes what the agent **knows**, or what the agent **does**. It is waste only when it misses both. | | *would have done it anyway* | *would not have* | | --- | --- | --- | | **already knows it** | waste | **worth stating** | | **does not know it** | rare | **the core case** | *The sky is blue* is waste. So is *write tests* — known, and already the disposition. *Stop before any destructive operation* is worth every token it costs, and a model knows exactly what a recursive delete does. **Knowing is not the same as pausing.** That passage changes nothing about what the agent knows and everything about what it does, which is the entire top-right quadrant and most of what a working agreement contains. *The subscription has no quota in this region, and these three VM sizes now return an error* is the bottom-right case. Not inferable from any repository, because it is a fact about an external system with a history. ## One axis is not enough, and the failure is instructive An earlier version of this bar had only the knowledge test: does a competent model already know this? Read strictly, that deletes every working agreement in the library. A model knows what force-pushing is, what personal data is, what an irreversible operation is. It is fluent in all of it, and fluency is not the thing being bought. What is being bought is the pause. **A bar that measures knowledge alone will delete exactly the passages with the highest value per token**, because those are the ones where the agent's knowledge is best and its default behaviour is worst. ## What happened when we applied it Twelve rootnotes, roughly fifteen thousand words. The result was not the one expected — an estimated forty per cent reduction came out at seventeen — and the distribution is the finding rather than the total. ``` accessibility-commitment 46% research-working-agreement 0% documentation-standard 29% writing-working-agreement 0% design-system-context 25% design-working-agreement 5% operational-runbook 24% working-agreement 9% ``` **Padding accumulates in documents that explain. It does not accumulate in documents that constrain.** The working agreements turned out to be almost irreducible. They are made of dispositions — what may run unattended, where work stops, what needs a human — and a disposition earns its tokens even when the knowledge behind it is universal. The documents that cut hardest had drifted into teaching. An accessibility commitment had become an ARIA tutorial. A documentation standard was explaining what belongs in an "About" section. A design system was re-deriving contrast rules any model states unprompted. Each was well written, correct, and paid for on every session for nothing. The tell is grammatical. **A document that says *here is how X works* is accumulating waste. A document that says *here you do X* mostly is not.** ## A third kind, which neither axis predicts The same passage — *accessibility is a floor, not a preference* — appeared in three separate rootnotes. Each instance passed both tests on its own. Together they were two-thirds waste. Duplication is invisible to any per-document check, including this one, and it arrives naturally: each document is written to stand alone, and standing alone is a virtue until the reader loads all three. It is worth a separate pass, and the fix is a pointer rather than a deletion, because the passage does belong somewhere. ## What this says about the evidence against context files A controlled study found that context files do not improve task success while costing over twenty per cent more in inference, and that repository overviews — the most common content in real files — do not help. That result is **exactly what you would expect if the average context file is mostly waste.** Their own data supports it: eight of the twelve developer-written files they examined contained a codebase overview, which is the top-left quadrant by their own measurement. If most of a file is padding, the cost is charged in full and the benefit of the useful fraction is diluted by everything around it. So the null result and the claim that written context works are compatible, and the reconciliation is a hypothesis rather than a finding: **the study may have measured the average quality of context files rather than the value of context files.** It is falsifiable, which is the point of saying it. Classify a file's passages, remove the waste, and re-run the benchmark. If trimmed files show the same null, this is wrong. ## The measurement that did not work, reported because it did not An attempt to put a number on the ratio failed, and the failure is worth more than the number would have been. The proxy asked whether a section contains a project-specific marker — a fill-in token, an explicit stop, a named constraint. It returned seventy-two per cent general, which would have been a striking figure to publish. It was wrong. It classified *what was rejected, and why* as generic, because that sentence contains no project-specific token while being the least inferable passage in the corpus. The proxy measured the presence of a phrase and was reported as measuring specificity. Calibrating it would have made it agree with whatever the corpus already looked like. **A metric that needs calibrating is proxying rather than measuring**, so no ratio is published here — only the distribution, which came from reading. ## What is not claimed The seventeen per cent is one corpus, written by one author who was establishing a house style, audited by the person who wrote most of it. It is an existence proof that the bar removes something real. It is not a rate anyone should expect, and a set written by several people would likely have more duplication and less teaching. Whether trimming improves task performance is untested here. The argument is that it cannot hurt — the removed passages changed neither knowledge nor behaviour by construction — but *by construction* is exactly the phrase that should make a reader want the experiment rather than the reasoning.