Reading Budget Discipline
Your context is finite; the data isn't. Reading it all back is the failure mode. Pull only the
decisive lines.
Quality degrades as the window fills — attention thins and earlier facts get lost in the middle — so
this applies across a long session where tool output accumulates, not only to single big reads.
Activation triggers
- About to open a large file, log, dump, binary, PCAP, decompiler output, or research page.
- Consolidating a folder of artifacts (a worker's
raw/, scan outputs, a .research/ workspace).
- Tempted to
read a whole file just to find one fact in it.
The rules
- Grep-first, then window: to find a fact in a big file,
grep/search for the line numbers,
then read a tight window (offset/limit) around the hit. Never whole-file to search.
- Head-first, windowed: when you must open a document, read the smallest artifact first (an
index/README, then the top of the main file). Continue with
offset only if the head is
insufficient.
- Extract, don't hoard: keep only the ≤few decisive lines/quote you need; leave the bulk on
disk. One fact needs one quote, not a page.
- Preview before full read: for an artifact/upload/large tool output, check size + a small
preview (metadata, head/tail, first few KB) before pulling the blob. Skip the full read when the
preview answers the question; otherwise paginate with bounded windows.
- Tail growing logs by byte offset: for streaming/appended logs (or long-running shell output),
read from the last-known byte forward — never re-scan from byte 0. Prefer streaming large tool
output to a side artifact/file over pulling it inline.
- Context quarantine: if a large artifact must be fully analyzed, delegate it to a fresh
sub-agent that reads it and returns a digest — keep the raw tokens out of your own window.
Anti-patterns
| Smell |
Instead |
read a 5k-line file to find one symbol |
grep the symbol → read a 20-line window |
| Loading a whole log/dump into context |
tail/grep the relevant span only |
| Re-reading files a worker already summarized |
consolidate from the returned report |
| Pasting a page to "keep it handy" |
quote the decisive lines; leave the page on disk |
| Downloading a whole artifact just to look at it |
preview metadata + head/tail first; fetch only if needed |
| Re-reading a growing log from byte 0 |
tail from the last-known byte offset |
| Pulling a huge command's stdout inline |
route it to a side artifact/file; read a window from disk |
Reprinting a big remote command's whole output (env, source files, /etc/passwd) to read one field |
filter on the remote (grep/awk/cut), return only the field |
| Running verbose commands over a raw interactive shell (each read echoes the command + prompt) |
write results to a file, grep the slice; keep per-turn output small |
Writing for others' budget
When you produce output others read back (a report, a research file), lead with a one-line answer +
a short TL;DR (the part actually read); push detail below and raw dumps into side files. Keep the
returned report compact — the files are the archive.
1---2name: reading-budget-discipline3description: Keep the context window lean and fight context rot: pull only the decisive lines instead of loading data back in full. Use before opening or searching a big file, log, dump, PCAP, decompiler output, or research page; before pasting large command/tool output inline; before reading a whole file or directory to find one fact; when consolidating a folder of worker artifacts; and in long multi-step sessions where tool output silently accumulates and buries earlier context. Enforces grep-first + windowed reads, preview-before-full-read, tail-by-byte-offset, extract-don't-hoard, and context quarantine (delegate a huge read to a sub-agent that returns a digest).4license: MIT5---67# Reading Budget Discipline89Your context is finite; the data isn't. Reading it all back is the failure mode. Pull only the10decisive lines.1112Quality degrades as the window fills — attention thins and earlier facts get lost in the middle — so13this applies across a long session where tool output accumulates, not only to single big reads.1415## Activation triggers1617- About to open a large file, log, dump, binary, PCAP, decompiler output, or research page.18- Consolidating a folder of artifacts (a worker's `raw/`, scan outputs, a `.research/` workspace).19- Tempted to `read` a whole file just to find one fact in it.2021## The rules22231. **Grep-first, then window**: to find a fact in a big file, `grep`/search for the line numbers,24 then `read` a **tight window** (`offset`/`limit`) around the hit. Never whole-file to search.252. **Head-first, windowed**: when you must open a document, read the smallest artifact first (an26 index/README, then the top of the main file). Continue with `offset` only if the head is27 insufficient.283. **Extract, don't hoard**: keep only the ≤few decisive lines/quote you need; leave the bulk on29 disk. One fact needs one quote, not a page.304. **Preview before full read**: for an artifact/upload/large tool output, check size + a small31 preview (metadata, head/tail, first few KB) before pulling the blob. Skip the full read when the32 preview answers the question; otherwise paginate with bounded windows.335. **Tail growing logs by byte offset**: for streaming/appended logs (or long-running shell output),34 read from the last-known byte forward — never re-scan from byte 0. Prefer streaming large tool35 output to a side artifact/file over pulling it inline.366. **Context quarantine**: if a large artifact must be fully analyzed, **delegate** it to a fresh37 sub-agent that reads it and returns a digest — keep the raw tokens out of your own window.3839## Anti-patterns4041| Smell | Instead |42|---|---|43| `read` a 5k-line file to find one symbol | `grep` the symbol → `read` a 20-line window |44| Loading a whole log/dump into context | tail/grep the relevant span only |45| Re-reading files a worker already summarized | consolidate from the returned report |46| Pasting a page to "keep it handy" | quote the decisive lines; leave the page on disk |47| Downloading a whole artifact just to look at it | preview metadata + head/tail first; fetch only if needed |48| Re-reading a growing log from byte 0 | tail from the last-known byte offset |49| Pulling a huge command's stdout inline | route it to a side artifact/file; read a window from disk |50| Reprinting a big remote command's whole output (`env`, source files, `/etc/passwd`) to read one field | filter on the remote (`grep`/`awk`/`cut`), return only the field |51| Running verbose commands over a raw interactive shell (each read echoes the command + prompt) | write results to a file, `grep` the slice; keep per-turn output small |5253## Writing for others' budget5455When you produce output others read back (a report, a research file), lead with a one-line answer +56a short TL;DR (the part actually read); push detail below and raw dumps into side files. Keep the57returned report compact — the files are the archive.
AeonDave