khosra/docs/context-economy.md

Context economy

How the agent spends context. The limit on this project is not typing speed, it is how much work fits in a session before the window fills — so bytes that buy nothing are features not built.

This doc has a floor and the floor wins. Every technique below is forbidden from buying: skipping the doc that owns a rule (CLAUDE.md §1), guessing an API instead of reading it, reporting success from a diff instead of a run (SKILL.md §4), keeping a test that was never seen to fail, or thinning generated code, content, tests, comments or commit messages. Those are all cheaper in tokens and every one of them has cost this project a defect. Frugality applies to presentation and discovery, never to the artifact or the evidence. When a saving and the floor disagree, pay.

1. Fewer turns beats fewer bytes

The whole context is re-sent on every tool call, so a six-call sequence costs roughly six times the window. Batch independent calls into one message. Where a sequence is known in advance or will be run again, write the script instead: one artifact that sets up, runs, probes and prints its conclusion — the live-reload check that measured the watcher is the shape to copy, and verify.sh is the same technique applied to the gates.

2. Read the compressed form first

In order of cost, stop at the first that answers the question:

Question	Cheapest answer
where does X live, what is in this package	docs/surface.md (generated; make surface)
what does this package offer callers	go doc ./internal/<pkg>
what does this behave like	its _test.go — a table states in 20 lines what 200 implement
why is it like this	decisions.md, state.md — never the code
what changed and when	git log --oneline -- <path>
how big is this before I open it	wc -l, or the manifest line in surface.md

Then read the range, not the file: grep -n to locate, Read with offset/limit. A whole-file read is for the doc that owns a rule you are about to assert, and for a file you are about to rewrite.

3. Let the machine find it

Discovery by mechanism beats discovery by reading.

• Break it and read the errors. Changing a signature: go build ./... returns the exact caller list, complete, in a form a grep can miss.
• scripts/verify.sh --list answers "does this gate exist" without running or reading anything.
• grep -c for "does this exist", -l for "which files", -n for "where". Context flags only when the surrounding lines are the answer.
• go test -run TestName over a full suite while iterating; the full suite once, at the end.

4. Shrink output at the source

Filtering inside the call is free. Filtering after it lands is impossible.

• ./scripts/verify.sh --quiet — two lines on green instead of forty-three. The pre-commit hook uses it. Use the loud form when a gate fails or you are auditing the gates themselves.
• Quiet and fail-fast flags by default: -q, --porcelain, --short, --oneline, -failfast, --stat before -p, and 2>/dev/null for known noise.
• Pipe through tail/grep -v/awk in the same call. Ten relevant lines, not four hundred.
• Long or noisy runs write to the scratchpad and get queried; never cat a lock file, a binary, or generated output.
• Sample rather than enumerate: two bundles out of thirty answer whether the shape holds.

5. Never pay for the same bytes twice

• No re-reading after Edit or Write — they fail loudly if they did not apply.
• A background command's output is read once, after it completes. Not while polling, and not quoted back afterwards.
• No restating the plan, then doing it, then summarising it. State once, report deltas.
• Write a fact down where it belongs the first time it is established (state.md, an ADR, a resume note in the queue file) so the next session reads a line instead of re-deriving it. A handoff note is cheaper than a compaction summary and loses less.
• Report file:line, never the code — the human has the file, and the reference is clickable.

6. Prose is the cheapest thing to cut and the easiest to overcut

Target density, not brevity: the same findings, numbers and caveats in fewer words. Cut preamble, recap, restatement, option surveys, and hedging. Do not cut a finding, a measurement, a stated assumption, or a caveat — a report that omits the caveat is not shorter, it is wrong.

What is enforced, and what is not

Three of these are mechanical. scripts/hooks/pre-commit regenerates docs/surface.md and stages it, so no commit can carry a stale one, and verify.sh compares independently for the clone that never set core.hooksPath. CLAUDE_LOC_MAX bounds the one file billed on every turn. --quiet exists to be used, and the hook uses it.

Everything else here is discipline — no script can see a redundant read, an unnecessary whole-file Read, or a report that padded instead of informing. That asymmetry is the reason this doc is short enough to be re-read, and the reason its floor is stated first.