Efficiency: speed and tokens¶
Built in¶
Most of these live in Gatework, the default pack, at the paths shown; rows marked core are in this repo.
| Technique | Where | Why it saves |
|---|---|---|
| Size-based execution mode | skills/brainrc-gatework/references/efficiency.md |
trivial/small tickets run inline: no subagent spawn overhead |
| Implementer writes its own tests by default | agents/brainrc-implementer.md |
one agent run per task instead of two |
| Batched review, parallel reviewers | skills/brainrc-gatework/SKILL.md |
one review pass per branch; concurrent read-only reviewers |
| Per-agent model tiers | model: in agents/*.md |
routine roles (verify, docs) on the cheapest tier; budgets stop a cheap model from using more tokens than it saves (the k9s trial verifier: 45k tokens, 18 tool calls before its budget was added) |
| Paths, not contents, in dispatch | references/handoff.md |
subagents load only what they need |
| Handoff blocks ≤ ~150 words; engine reads only the newest | references/handoff.md |
main thread stays small across long runs |
Command output to .runs/, read summaries |
references/efficiency.md |
test/plan logs never flood context |
Plan summarized via terraform show -json + jq |
skills/brainrc-terraform |
resource actions instead of full plan text |
| Checks scoped to changed packages/roots during implement | references/efficiency.md |
faster loops; full run once at verify |
| Domain skills load on demand | Agent Skills progressive disclosure | only the stacks touched cost tokens |
| Short, de-duplicated global rules | rules/ (core) |
rules load in every session of every tool |
| Always-loaded token budgets | validate (core: CORE_ALWAYS_BUDGET, pack max_always_tokens) |
rules and descriptions can't grow unnoticed; tokens shows each source against its budget (packs) |
Long skills keep catalogues in references/ |
e.g. skills/brainrc-unslop |
the body read on every use stays short |
| Static role files, variable text last | agents/, dispatch prompt |
stable prefixes for prompt caching |
Measure with the metrics in each run's retro.md, plus token/cost tools below.
Metrics rollup¶
scripts/retro_report.py rolls up specs/*/state.json across runs. It is offline and read-only.
python3 scripts/retro_report.py [--root DIR]... [--json] [--ccusage]
--root (repeatable, default .) is a project root holding specs/*/state.json, or a specs dir.
Output is a Markdown table per run plus averages overall and by size, mode, domain, and final stage.
Minutes throughout. unknown means not recorded and is never counted as 0; averages show n, the runs where the value is known.
| Number | Meaning |
|---|---|
| Total min | start of run to done; unknown for in-progress or blocked runs. For a watched run it includes waiting for the PR to merge |
| Gate wait min | time parked at approval gates, waiting on a human; unknown if it exceeds total (inconsistent timestamps), with a warning, so it stays out of averages |
| Agent min | total minus gate wait: time the agent worked |
| First-pass | share of review passes that found nothing to fix; the aggregate is the average of per-run rates (with n) |
| Retries | each time a task goes back to the implementer |
| Interventions | each time the user has to step in outside a gate (answering a blocked stop, correcting the agent mid-stage) |
| Wave ratio | summed task minutes over wall minutes of parallel waves (above 1 means parallelism paid off) |
| Blocked stops | a run's current blocked reason plus each past blocked handoff in its log.md; counted once per stop, with the reasons listed per group |
| Criteria | passed/total acceptance criteria |
| Outcome | merged, abandoned (PR closed unmerged), or unknown (still open or not watched) |
| Post-merge | result of the post-merge verify: pass, regression, unverified, or unknown |
| Time to merge | PR opened to merged, in minutes, from timestamps; unknown if either is missing |
| Review rounds | review rounds handled by watch (watch.review_rounds) |
| CI failures | red checks recorded in watch.ci_failures, own and external |
| Warnings | inconsistent state, e.g. stages out of order; the run still counts |
Aggregates add Avg time to merge (with n), Merged and Abandoned run counts, and Regressions (runs whose post-merge verify found one). Runs without the watch fields show unknown in every new column, never 0.
Tokens and cost are not in state.json. They come only from --ccusage, which runs
ccusage daily --json for the date range of the reported runs, widened by one day on each side (ccusage buckets by local day, run stamps are UTC), and gives one period total, not a
per-run figure. Without the flag, or if ccusage is missing, fails, or the runs have no dates, tokens and cost stay null. The ccusage
flags and JSON shape are assumed from its docs and untested against a real install.
JSON schema (--json, schema_version 2)¶
One document on stdout. Unknown values are null.
| Field | Content |
|---|---|
schema_version |
2; bumped on breaking changes |
runs[] |
one record per run: path, slug, size, mode, domains, stage, blocked_reason, total_minutes, wait_minutes, agent_minutes, stage_minutes (per stage), gate_rework (per gate), first_pass_rate (0-1), retries, interventions, waves, wave_ratio, criteria_passed, outcome, post_merge, time_to_merge, review_rounds, ci_failures, blocked_stops, warnings (new fields in version 2; null when unknown) |
skipped[] |
runs that could not be read: path, reason |
aggregates |
runs, overall, by_size, by_mode, by_domain, by_stage, domain_note, blocked_stops; each group has runs, averages ({avg, n} per field), stage_minutes and gate_rework ({avg, n} per key), blocked_stops (count, reasons), and the counts merged, abandoned, regressions (runs by outcome / post_merge; averages.time_to_merge is the mean) |
usage |
requested, available, since, until, tokens, cost, note |
Optional external tools (researched 2026-09)¶
None are required. Evaluate against your own retro.md numbers before adopting. Savings
figures are as reported by the linked sources, not measured here.
| Tool | What it does | Reported effect | Notes |
|---|---|---|---|
| ryoppippi/ccusage | Token/cost reports from local Claude Code logs | measurement | Start here: measure before optimizing |
| rtk-ai/rtk | CLI proxy that compresses noisy command output | 60–90% on log-heavy output | Overlaps our .runs/ discipline; helps in ad-hoc sessions |
| oraios/serena | LSP-backed symbol-level code navigation/editing (MCP) | fewer full-file reads | Strong fit for large Go codebases |
| Mibayy/token-savior | Symbol-level navigation MCP | ~43% in one comparison | Best on typed languages |
| JuliusBrussee/caveman | Terse-output skill/hooks | ~38% on prose output | Little effect on tool-heavy runs |
| musistudio/claude-code-router | Routes requests to cheaper models/providers | cost, not tokens | Our model: tiers cover the Claude-only case |
| mksglu/context-mode | Offloads large tool outputs to a searchable store | 20–98% on big outputs | Elastic License v2 (not OSI) |
| Fission-AI/OpenSpec | Lightweight SDD with delta specs | ~250 vs ~800 lines per change vs spec-kit | Idea source; see roadmap for delta/living specs |
Skip tools under non-commercial licenses if you use this at work (e.g. PolyForm Noncommercial).
Sources: computingforgeeks tool comparison, OpenSpec concepts, OpenSpec vs Spec Kit, ccusage.