docs: the token budget — measured spend, staged design, and the gates that prove it

[buzzdan]

What

A design for cutting the plugin's token spend without changing what the rules say, grounded in a measurement of the go-2.11.0 baseline traces, plus the instrument that produced the numbers. Rebased onto main after #59 and aligned with docs/eval-return-experiments.md.

• docs/token-budget.md — the measured problem, six stages (S1 hunters read the scope once, S2 rules by reference, S3 agent budgets and a ban on improvised general-purpose agents, S4 skill-text diet, S5 hunter-count experiment decided by recall, S6 a Go analyzer for the mechanical falsifying questions), the two gates every stage must pass (no grader moves beyond the noise floor; billed tokens fall beyond the run-to-run swing), the per-stage procedure, reference floors, targets and risks.
• scripts/spend-report.py — reads every trace.jsonl under a results or unpacked-baseline directory and prints per-run billed tokens and cost, per-tier attribution of what filled the context, and per-agent-kind turns and Read calls. Reference implementation until the same report lives in ldd-eval.
• docs/eval-return-experiments.md — cross-links only: experiment 4 points at the Go accounting done here, gate 0.5 and the "How to measure" prose link the page instead of naming the PR, and the handbook-plus-lint-gates arm links S6. Frontmatter and index line unchanged.
• docs/index.md and docs/eval-baseline.md — index line and a pointer from the cost section.

The proofs plan, aligned with the return experiments

• The mechanical stages S1 to S4 are gate 0.5 of the gated order in eval-return-experiments; S5 and S6, which change the plugin's shape, wait until that order's gate 1 has run.
• Proofs are bought in two pairs, not one per stage: S1 with S2 on both tiers ($58), then S3 with S4 on both tiers ($42). If the first pair fails the behavior gate, bisect by running S1 alone on the review tier (~$20). Development and proof are separable; nothing is being spent now.
• The rules-file arm everywhere is the generated handbook, coding-rules/*.md as generated, never a hand-condensed summary.
• The handbook-plus-lint-gates arm (rule greps in golangci-lint and ruff or hooks at zero tokens) is the delivery S6's analyzer is the mechanism for.
• Gate 1's cost bound in eval-return-experiments uses this page's definition of billed tokens and its worst-run-versus-best-run rule.
• The reference floors section links experiment 8 (the same none / handbook / handbook-plus-lint-gates / plugin design on py-mini) and gate 0.5, which runs the three plugin-free cells in parallel with the diet.

Why

On the Go baseline (39 runs, 131M tokens, $78) the repository work is 2 to 8 percent of billed tokens. Subagents are 53 percent of the review tier (hunters reading one file per turn; 14 agents reading the same 83 files, 233 Read calls), the fixed first-call context re-billed every call is 22 to 27 percent, and plugin text carried in the main context is 9 percent. One improvised general-purpose agent cost $7 of a $7.75 quickfix run. Rule greps, the first suspect, are about 1 percent.

Checks

• Docs gate run directly (bash go-linter-driven-development/scripts/check-repo-brain.sh ., since rsync is missing in the container): clean. Every link target exists on the branch.
• No generated plugin directory or coding-rules/ file touched, so task check drift is unaffected.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SAr6GrXQGq7nx2mwCoifdQ