init

ideas/token-conservation.md

@@ -0,0 +1,49 @@
+# Token conservation
+
+Status: parked
+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
+
+1. Batch tool calls — one Bash call per phase, not per command.
+2. 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.
+3. Line ceiling on `CLAUDE.md` in `budgets.env`, gated like any other budget.
+4. Targeted reads — `grep -n` plus `Read offset/limit`; whole-file reads only for the doc that
+   owns a rule being asserted.
+5. Evidence proportional to risk — one case for a behaviour change, a full matrix only for a gate
+   or a security boundary.
+6. 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.
+
+## 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.