Files

T

make context a budget the harness enforces

Adopts ideas/token-conservation.md, parked 2026-07-28, plus the disciplines
the human added: read the compressed form first, discover by mechanism,
shrink output at the source, never pay twice for the same bytes.

docs/context-economy.md owns all of it and leads with a floor, because
every cheap failure mode is also a token saving — skipping the owning doc,
guessing a signature, reporting from a diff, thinning a test — and each has
already cost this repo a defect. Frugality is for presentation and
discovery, never for the artifact or the evidence.

Mechanical, not remembered:

- scripts/surface.sh generates docs/surface.md — every top-level
  declaration with its line, 261 lines standing for 3757 of source. The
  pre-commit hook regenerates and stages it, so it cannot be stale, and
  verify.sh compares independently for a clone that never set
  core.hooksPath. The hook refuses a commit with unstaged .go changes,
  since what it generated describes the working tree, not the commit.
- verify.sh --quiet: 48 lines of gate output become 1. The hook uses it.
- CLAUDE_LOC_MAX=150, the only budget billed per turn rather than per read.

Both new gates were watched failing before being kept: a doctored
surface.md, and CLAUDE_LOC_MAX temporarily set to 5.

state.md's inventory loses its LOC column. It had already drifted on six
files (content.go 381→450, render.go 447→454, web.go 206→217, check
216→223, watch 129→137, chrome 105→110) which is what a number written in
two places does; the generated file owns sizes now, the table owns purpose.
The subagent question is recorded there as the one open decision, with the
case for and against written out in the idea file.

2026-08-01 02:16:11 +06:00

4.2 KiB

Raw Blame History

Token conservation

Status: adopted → docs/context-economy.md + ADR-0053 (2026-08-01). All six mechanisms landed, plus the compressed-form, machine-discovery and quiet-output disciplines the human added. The open question below is the only part still undecided; it is also recorded in state.md "Open questions". Raised: 2026-07-28

Why it came up

Development pace is limited by session and usage limits, not by typing speed. Cutting token cost per feature buys more features per session. The goal is explicitly conserve tokens without lowering output quality — not "be terse and worse".

What is already established

Do not re-derive these.

Turn count dominates, not file size. The whole context is re-sent on every tool call, so a six-call verification sequence costs roughly 6× the context. Batching is the biggest lever.
CLAUDE.md is the most expensive file per byte in the repo — it is re-sent every turn.
Agent prose is a large, entirely self-inflicted cost. The target is density, not brevity: same information, fewer words. Length follows content; padding, restatement, hedging and rhetorical closers do not.
Two accepted rules cost tokens on purpose and are worth keeping: hard rule 8 (docs ship with the change) and the topic-ownership read floor. The ownership table is what keeps the floor cheap — it sends you to one doc instead of a grep sweep.

The six mechanisms, ranked by saving

Batch tool calls — one Bash call per phase, not per command.
Prose density in reports and replies — cut restatement and flourish, keep every finding, number and caveat. Biggest win, costs nothing. Not a length cap: truncating information is not a saving.
Line ceiling on CLAUDE.md in budgets.env, gated like any other budget.
Targeted reads — grep -n plus Read offset/limit; whole-file reads only for the doc that owns a rule being asserted.
Evidence proportional to risk — one case for a behaviour change, a full matrix only for a gate or a security boundary.
Never re-read after Edit; run verify.sh once per feature, at the end.

Open question — needs the human

Subagents for fan-out search. Dispatching "find every place X appears" to a subagent keeps its file dumps out of the main context: you pay for the conclusion, not the search. A real multiplier on exploration-heavy work. Currently disallowed unless explicitly requested, so it is a policy call, not a judgment call. Deferred again on 2026-08-01, with the case laid out:

For. The criterion is read volume ÷ conclusion length. /audit, /refresh-docs and /invariants all read thousands of lines to produce a verdict of twenty, so their ratio is ~100:1 and the reading is pure waste in the main window. Several passes could run at once. A subagent that goes down a wrong path costs nothing here, which makes speculative exploration cheap for the first time.

Against. Four real costs. (1) The subagent reads under its own judgment, not the read-order discipline in CLAUDE.md §1 — the thing that keeps this project's read set small is exactly what a delegated agent is worst at honouring. (2) A verdict without its evidence cannot be audited: "no abstraction has earned extraction" is only trustworthy if the counters were read correctly, and the report is all that comes back. (3) Findings arrive as prose to be re-verified, and re-verification of a wrong report costs more than the original read would have. (4) Total tokens go up, not down — the saving is entirely in this window, which matters for session length and not at all for usage limits.

Where it is clearly right. Read-only sweeps whose output is a list of locations, where being wrong is visible immediately: "every doc mentioning the old form after a rename", "which files import X".

Where it is clearly wrong. Anything that decides something — a verdict, an earn-it call, an invariant, whether a warning is a defect. Those need the evidence in the window where the decision gets made.

Cheapest next step

Apply 1–6 as one batched change: CLAUDE.md (efficiency rule), SKILL.md (report cap, evidence proportionality), budgets.env + verify.sh (CLAUDE.md line ceiling). Trips the HARNESS.md coupling gate by design. Estimated one feature-sized change.

4.2 KiB Raw Blame History Unescape Escape