context-minimization · diff
git:20260502.548cfac to git:20260606.d8997b5
58 added, 10 removed. Audit A to A.
---
name: context-minimization
- description: "Use continuously during long tasks. Teaches how to read less, output less, and keep the LLM context window lean and fast."
+ description: Use when a task runs long and the context window is filling -- large files are being read whole, command output is flooding the transcript, or responses are getting verbose and slow.
---
- # Context Minimization
+ ## Purpose
- Your context window is the most precious resource. Large contexts make you slow, expensive, and prone to hallucinations.
+ Your context window is the most precious resource. Large contexts make you slow, expensive, and prone to hallucinations. Treat every token read or written as a cost, and apply a continuous discipline: read less, output less, keep the window lean.
- ## The Rules of Lean Context
+ ## When to Use
- 1. **Surgical Reads**: Never use `cat` or `read_file` on a 2,000-line file without `start_line` and `end_line`. Always use `grep` first to find the relevant line numbers.
- 2. **Silent Commands**: Always append `--silent`, `-q`, or redirect stderr/stdout to `/dev/null` for commands that produce massive logs (like `npm install` or verbose builds) unless you specifically need to debug them.
- 3. **Pagination**: Disable pagers for all terminal tools. E.g., `git --no-pager log`.
- 4. **Terse Responses**: Do not explain what a tool does before calling it, unless safety requires it. Do not repeat the user's instructions back to them verbatim.
- 5. **Close Files**: Once you are done looking at a file, stop referring to it.
- 6. **Parallel Ops**: If you need to search 3 files, run 3 parallel grep/read calls in a single turn instead of sequentially. This saves turns, which saves context repetition.
+ - Continuously during any long, multi-step task
+ - About to open a large file (hundreds or thousands of lines)
+ - A command is about to emit massive logs (installs, verbose builds)
+ - Responses are drifting into explanation and restatement
+
+ ## Inputs
+
+ - The current task and the files/commands it requires
+ - Awareness of which files are large enough to need targeted reads
+
+ ## Workflow
+
+ 1. **Before reading: search, do not slurp.** Never read a 2,000-line file whole. Locate the relevant region first, then read only that range.
+
+ ```bash
+ grep -n "functionName" src/module.ts # find the line numbers
+ ```
+ Then read only the surrounding window (e.g. lines 120-160), not the entire file.
+
+ 2. **While reading: parallelize, do not serialize.** If you need to inspect 3 files, issue 3 reads/searches in a single turn rather than one per turn. Fewer turns means less context repetition.
+
+ 3. **When running commands: silence the noise.** Suppress bulk output unless you need it to debug, and disable pagers so output is not re-printed.
+
+ ```bash
+ npm install --silent # drop install chatter (-q on tools that use it)
+ git --no-pager log -n 20 # no interactive pager
+ some-build 2>/dev/null # discard stderr you do not need
+ ```
+
+ 4. **When outputting: stay terse.** Do not explain what a tool does before calling it unless safety requires it. Do not repeat the user's instructions back verbatim. State the result, not the process.
+
+ 5. **After reading: close the file.** Once you are done with a file, stop referring to it and do not re-read it. The harness already tracks what you have seen.
+
+ ## Output
+
+ - Targeted reads of only the needed line ranges
+ - Quiet, pager-free command invocations
+ - Concise responses with no restatement or pre-call narration
+
+ ## Verification
+
+ - [ ] No whole-file read of a large file without a line range
+ - [ ] Searched for line numbers before reading a large file
+ - [ ] Independent reads/searches batched into a single turn
+ - [ ] Noisy commands silenced and pagers disabled
+ - [ ] Responses contain no instruction restatement or tool pre-explanation
+
+ ## Failure Modes
+
+ - **Slurping the whole file** — reading an entire large file when a grep-located range would do; it floods context and buries the relevant lines.
+ - **Serial reads** — opening files one per turn instead of batching, multiplying context repetition across turns.
+ - **Log flooding** — running verbose installs or builds without silencing, drowning the transcript in output you never needed.
+ - **Narrating everything** — restating instructions and pre-explaining tool calls, spending output tokens on filler.
+