Your optimisation plan

How to use the plan#

The order is an engineering judgment, not a measured payoff curve. The proposed sequence starts with a baseline and reversible changes, then moves to habits, evaluation and optional architecture. It does not establish that Phase 1 or the first seven hours deliver most of the benefit.

The total of about 16 hours over six weeks is an authored planning estimate. Every phase duration is a proposed budget, not an observed average. Pass a phase's gate before continuing, and stop after any phase once your own measurements satisfy the stop rule.

Three rules make it work:

1. Do not skip Phase 0. Every later gate compares against the Phase 0 baseline. Without it you cannot tell whether anything helped, and in six months you will have a stack you cannot prune.
2. Pass a phase's gate before starting the next. Adopting five things at once produces a result nobody can attribute.
3. Stop when the stop rule fires. Context management has a stopping point.

Phase 0: Baseline (1.5 hours, week 1)#

You cannot optimise what you have not measured, and you cannot claim an improvement without a "before".

Do:

1. Prefix tax. Open a fresh session, send a single ., record the input tokens. Write it down with the date and harness version.
2. Tool inventory. Dump every tool schema and count tokens, in total and per server. Then list every tool actually called in your last 20 sessions.
3. Session profile. Take your three longest recent sessions and bucket their tokens by segment with the budget audit. You are looking for the largest segment you control.
4. Command ranking. Rank shell commands by total output tokens. Expect three to five commands to be over 70% of tool output.
5. Cache hit rate. Record it if your harness or provider reports it. If not, write down that you cannot measure it: that is a finding.
6. Failure sample. For your last 10 failed or unsatisfying tasks, answer one question: was the decisive file ever read? Tally starvation (never read) against dilution (read and ignored).

Date: ____________   Harness version: ____________
T1   prefix tax                   _______ tokens
T2   tool-definition share        _______ %
T3   defined : called             _______ : 1
T6   peak utilisation             _______ %
T10  tool-result share            _______ %
T24  cache hit rate               _______ %   (or "cannot measure")
T19  starvation : dilution        _______ : _______
Largest segment I control:        ____________________

Gate: the numbers are written down somewhere you will find them again. That is the whole gate.

Phase 1: Deletion (2.5 hours, week 1)#

The first intervention to consider when the audit finds dead or duplicate surface. Deletion is reversible when coverage is verified and rollback is kept; instruction pruning changes behaviour, so measure it separately. This is a sequencing recommendation, not a measured yield ranking.

Do:

1. Review MCP servers with zero calls in a representative 20-session sample. Remove candidates only after task-coverage verification; keep a rollback. (30 min)
2. Review MCP servers that duplicate the shell: GitHub if you have gh, filesystem if you have file tools, database if you have psql, fetch if you have curl. If a server is a security control, keep it, but write that decision down; otherwise verify coverage before removal. (30 min)
3. Enable deferred tool definitions for what survives, if your harness supports them. (15 min)
4. Write ignore files: node_modules/, dist/, build/, *.lock, __generated__/, vendor/, snapshots, fixtures. (15 min)
5. Apply the inference test to your instruction file: could a competent engineer infer this line from the repository in two minutes? If yes, delete it. Aim for at most 150 lines, and move the three rules you most need obeyed to the end. Delete rules that describe refactors already done. (45 min)

Gate: re-measure prefix tax, tool share and the defined : called ratio — chapter 8's audit does this systematically. Target a 50–90% prefix-tax reduction when dead or duplicate surface dominates D; measure it before treating it as a target. Then run 10 normal sessions and count occasions where a deleted capability was missed. Expect zero; if more than one, restore that specific server and note why.

Phase-specific estimate: 25–35% of the window back when unused or duplicated capabilities dominate D. This is a derived planning estimate for that condition, not an observed average or a programme-wide payoff; test it against your baseline.

Phase 2: Prevention (3 hours, week 2)#

Shape output before it becomes context.

Do:

1. Wrap your four loudest commands. Each wrapper applies the quiet flag, filters obvious noise, sends the full output to .agent/logs/, and returns a digest plus the path. (2 h)
2. Build in the pass/fail asymmetry. Passing test runs return one line; failing runs return the full trace. Prioritise this candidate when noisy test output is a measured source of waste.
3. Truncate head-and-tail at 2–8K tokens with a 30/70 split for anything not wrapped. Never truncate the middle. (15 min)
4. Create a gitignored .agent/ directory. (5 min)
5. Set search defaults: rg -C 8 plus your standard exclusions. (15 min)
6. Check the cache hit rate. If Phase 1 or 2 lowered it, something you did made the prefix dynamic. Find it and revert. (15 min)

#!/usr/bin/env bash
# Run the test suite; return one line on success, the failure detail on failure.
mkdir -p .agent/logs
log=".agent/logs/test-$(date +%s).log"
if pytest -q --tb=short "$@" >"$log" 2>&1; then
  echo "PASS: $(tail -n 1 "$log")   (full log: $log)"
else
  echo "FAIL (full log: $log)"
  head -n 20 "$log"          # the command and first failures
  echo "…"
  tail -n 60 "$log"          # errors cluster at the end
  exit 1
fi

Gate: re-measure tool-result share, task outcomes, cache hit rate, and priced input/output costs using your provider's rates. Practitioner reports describe 60–90% less command output P, a token-volume hypothesis rather than a cost estimate. Keep shaping only if the measured quality and priced-cost results justify setup and maintenance; count re-runs with more verbose flags over 10 sessions, and loosen the digest if they rise.

Phase-specific estimate: 20–30% context-volume reduction when output waste dominates D. This derived planning estimate is conditional, not a cost estimate; measure your sessions and priced costs to see whether it applies and whether it combines with Phase 1.

Phase 3: Retrieval (2 hours plus a habit, week 3)#

The first phase that needs behaviour change, which is why it is third.

First, read your Phase 0 failure tally. It decides what you do.

• Mostly starvation (decisive file never read): a recall problem. Do items 1 and 2. Do not reduce retrieval volume; that makes it strictly worse.
• Mostly dilution (read and ignored): a precision problem. Do items 1, 2 and 3.

1. Install a symbol-level retrieval tool if your stack has language-server support. Budget five to eight tool slots for it. (1 h)
2. Adopt locate → inspect → read: grep -l, then grep -n, then read the symbol. Expand along the reference graph, not the file.
3. Stop pre-loading. Replace any codebase overview with a pointer seed under 2,000 tokens. (1 h)
4. Re-read before re-editing. Your own edits invalidate your own context.

Gate: sample 20 reads and compute read-utilisation — chapter 5 owns the retrieval design. Compare the median with your Phase 0 baseline; roughly doubling it from under 10% to 15–25% is a derived planning expectation, not a guaranteed result D. Re-run the failure tally on the next 10 failures: the balance should move toward dilution. If it moved toward starvation, you cut too much; widen the pointer seed.

Phase 4: State and boundaries (3 hours, week 4)#

Goal: test whether explicit state and boundary practices make long tasks more recoverable.

1. Adopt a plan-file convention with goal, constraints, decisions, ruled out, and next step. Cap it at 80 lines; update it at state changes; include "last updated at turn N". (1 h)
2. Adopt an offload convention with self-describing stubs: a3f9.log (14KB) — npm ci, exit 0, 2 peer-dep warnings, never just a3f9.log (14KB). (30 min)
3. Replace your compaction prompt with the explicit schema. Worth up to 6.5 SWE-bench points S, and it is a text edit. (30 min)
4. Set compaction rules: right after a test passes or a sub-task closes; never mid-debug or when stuck; never more than once per session; never with fewer than five turns left.
5. Evaluate a plan-file reread as a possible first orientation action after compaction. TRACE reports a post-compaction risk in AppWorld but did not test this recovery practice S.
6. Adopt reset triggers: a second compaction is needed, the same action repeats three times, a poisoned fact appears, the task pivots, or utilisation passes 70% with a lot left.
7. Adopt a handoff template with file:line pointers and verification commands with their results. (30 min)

Gate: post-boundary re-fetch rate under 2, compactions per session at most 1, and, over 10 long sessions, zero re-proposals of an approach the plan file lists as ruled out.

Why adoption stalls here: the payoff is invisible on short tasks.

Phase 5: Measurement (4 hours, weeks 5–6, optional)#

Only if you intend to keep making context changes. If Phases 1–4 solved your problem, skip this and go to the stop rule.

1. Build a small evaluation set: 30–40 replayed tickets, repository pinned to the commit before each fix, stratified by size and subsystem. Check for leakage by running one arm with retrieval disabled. (2 h) Chapter 9 owns the protocol.
2. Build a k = 2 runner that computes Pass@2 and Pass². (1 h)
3. Run one paired A/B on the change you are least sure about, analysed with McNemar. (1 h plus compute)
4. Add the two missing instruments: post-boundary re-fetch rate and Pass² ÷ Pass@2. Neither exists off the shelf.

Gate: you can say, with an interval, "our configuration solves X of 40 tasks reliably, at Y cache-adjusted cost per solved task", and you know how wide the interval is.

Worth it if you will make more than three further context changes. Not otherwise.

Phase 6: Advanced (only if measurement demands it)#

Do not start these without a measured reason from Phase 5.

The stop rule#

Check monthly; the thresholds come from chapter 10's catalogue. Stop optimising context when all of these hold:

• Cache hit rate over 70%
• Defined : called tools under 3:1
• Tool-result share under 35%
• Read-utilisation over 15%
• Post-boundary re-fetch under 2
• Pass² ÷ Pass@2 over 0.85, or you are not compacting

This is a proposed operating stop rule, not a measured point where context work stops helping. When all six conditions hold, pause this sequence and check whether model choice, task decomposition or verification is the next constraint before investing further.

The maintenance loop#

Context management regresses. Tool surfaces regrow within a quarter without a recurring audit P; the rest of the prefix follows, so budget that you are back at baseline within two quarters D.

Quarterly, 30 minutes:

1. Re-run Phase 0's measurements.
2. Compare them with last quarter.
3. For any metric that regressed, re-apply that phase.
4. Delete any instruction rule that was neither violated nor relevant all quarter.
5. Review any tool with zero calls this quarter; if the sample is representative, verify task coverage and remove it with rollback.
6. Delete any stale memory entry.

Three of the six steps are deletions, and the other three exist to catch whatever crept back. That balance is not an accident.

The plan on one page#