context-budget-triage
verifiedb38ad2c5-b9fb-416c-8ded-e25784328481
Decide what belongs in the agent's live context vs what to offload to files/notes so long tasks don't degrade. Use when a session is getting long or context is filling up.
Metadata
Skill file
# Context Budget Triage
Use when a session is getting long or the context window is filling up. The goal:
keep only what is needed for reasoning in the live context, and move everything
else to files so nothing important is lost and nothing irrelevant crowds out
reasoning.
## 1. The triage buckets
For every piece of information in context, assign one of three buckets:
| Bucket | What goes here | Example |
|---|---|---|
| **Keep live** | Current task, open questions, recent errors, decisions not yet recorded, the code you are actively editing | "the failing test says `expected 302, got 500`" |
| **Offload** | Full logs, old diffs, boilerplate, earlier discussion summaries, resolved questions | the 200-line traceback, the full `git diff` from 3 steps ago |
| **Delete** | Stale noise: superseded plans, wrong turns already abandoned, duplicate content, tool output you already acted on | "let me try approach A" after you switched to B |
The test for each item: *will I need to refer to this again to make the next
decision?* No → offload or delete.
## 2. Offload targets
Offloading does not mean discarding — it means moving to a durable file and
replacing the content in context with a **reference to the path**.
| What to offload | Where |
|---|---|
| Full error/traceback output | Append to `notes/errors.log` or scratchpad |
| Old diffs / file contents | Save to `notes/` and reference the path |
| Summaries of completed subtasks | Append to the working-notes scratchpad |
| Boilerplate / config you read once | Note the file path, drop the content |
| Resolved discussion threads | Replace with a one-line decision record |
```text
# BEFORE (offload): 300 lines of traceback pasted in context
# AFTER: "See notes/errors.log:42 — the KeyError is on line 118 of parser.py"
```
## 3. The checkpoint-and-compact loop
For multi-hour tasks, checkpoint periodically instead of waiting until context is
full:
```text
every N steps (or when you notice context bloating):
1. Write a checkpoint: current state, decisions made, next action (see
session-handoff-resume template).
2. Offload bulky content (logs, diffs) to files.
3. Replace offloaded content in context with path references.
4. If available, compact/summarize the conversation history.
5. Re-read the checkpoint and continue.
```
The checkpoint is the anchor — if the compaction loses detail, the checkpoint file
carries the essential state forward.
## 4. A worked triage pass
You are 40 steps into a debugging session. Context contains:
| Item | Bucket | Action |
|---|---|---|
| The exact failing command + 1-line error | Keep | still actively debugging this |
| 300-line traceback | Offload | append to `notes/errors.log`, keep "see errors.log:42" |
| Diff of your last 3 edits | Offload | save to `notes/last-changes.diff`, reference path |
| The abandoned "use Redis" plan | Delete | you switched to "use Postgres"; drop it |
| A resolved API question | Offload | replace with "API accepts `?limit=100` (decided)" |
| The current hypothesis | Keep | this drives the next step |
## Guardrails
- Do **not** offload decisions you will need in the next few steps — offloading is
for things you will not need *imminently*, not for your active working set.
- Do **not** keep full logs inline until they crowd out reasoning — offload them
early, keep only the one-line signal.
- Do **not** delete content you cannot regenerate (exact user requirements, test
results you have not recorded).
- Do write a checkpoint *before* compacting, so essential state survives.
- Do reference file paths instead of re-pasting content.
## Pitfalls
- **Offloading decisions you'll need** — moving "we decided X" out of context and
then acting contrary to it a few steps later because it is no longer visible.
- **Keeping full logs inline** — 500 lines of traceback sitting in context,
crowding out the reasoning that would solve the bug.
- **No checkpoint before compaction** — compacting without a durable note loses
the state that matters.
- **Re-pasting instead of referencing** — pulling the same 300-line diff back into
context because you offloaded it without noting the path.
- **Holding stale noise** — abandoned approaches and superseded plans still in
context, confusing what the current plan is.
## Verify / Checklist
- [ ] Every context item has been assigned keep / offload / delete.
- [ ] Offloaded content is saved to a file and replaced with a path reference.
- [ ] A checkpoint (state + decisions + next action) exists before any compaction.
- [ ] No full logs or large diffs remain inline; only one-line signals.
- [ ] Active working set (current task, open questions, hypothesis) is still live.
- [ ] Nothing irreplaceable (unrecorded decisions, user requirements) was deleted.Attached files
No attached files.