Files

T

uncap the clarifying questions, and stop the harness asserting numbers

The cap was arbitrary and the wrong lever: what matters is that a question's
answer changes the code, not how many such questions a request happens to carry.
A request with six real forks now gets six, batched into one turn — splitting
them to look brisk costs the human more than asking once. The instruction to ask
is unchanged and still gated by "each with a default so silence answers".

The rest is numbers the harness had no business holding. Three kinds, swept
across every harness doc, and none of them wanted machinery.

Restated values were the real fault: HARNESS.md carried the ceiling figures,
which docs/README.md's single-source table says live in scripts/budgets.env and
nowhere else. Prose repeating a value is a copy waiting to go stale, which is
exactly the rule I was quoting at everything else. The ADRs keep old and new, as
an append-only log should; the harness names the concept and points.

Illustrative figures — how long verify.sh prints, surface.md against the source,
how much the binary grew — drift every commit and carry no decision, so they now
say "a line per gate", "an order of magnitude smaller", "roughly a third".

Counts that restate their own list are the same fault in miniature: "the three
gates people skip", "six commands", "three pieces of it are mechanical", "two
sibling folders", "three cases, no fourth". Each is a number that goes wrong the
day the list beneath it changes, and none of them was doing any work.

Left alone deliberately: values with no other home — the ~50% overrun, the
72-character subject, 40 lines of stdlib over a dependency, toolchain versions.
Those are the source, not a copy of one.

No gate for this. It would have to guess which four-digit number is a budget
rather than a year, an ADR, an HTTP status or a Go version, and a gate that
fires on correct prose is a defect.

2026-08-02 00:56:41 +06:00

5.0 KiB

Raw Blame History

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 one per gate. 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.

5.0 KiB Raw Blame History