Merge #447: add Context Budget Management to context-engineering

docs(context): add Context Budget Management section

skills/context-engineering/SKILL.md

@@ -118,6 +118,8 @@ Long conversations accumulate stale context. Manage this:
 - **Summarize progress** when context is getting long: "So far we've completed X, Y, Z. Now working on W."
 - **Compact deliberately** — if the tool supports it, compact/summarize before critical work
 
+For the proactive discipline that makes these last resorts unnecessary — what to cut first, what to protect, and when to start — see **Context Budget Management** below.
+
 ## Context Packing Strategies
 
 ### The Brain Dump
@@ -177,6 +179,49 @@ Key files: validation.ts, errors.ts, db.ts
 
 Load only the relevant section when working on a specific area.
 
+## Context Budget Management
+
+The context window is not a filing cabinet — it's a working desk. As a session runs, conversation history, tool output, and exploration accumulate. Most of it becomes deadweight. Budget proactively: waiting until the window is full causes abrupt quality drops; managing regularly keeps the agent coherent through long tasks.
+
+**Start trimming at 75% capacity, not 100%.** By the time the window is genuinely full, the model's attention is already fragmented across too many signals. The 75% threshold gives room to compress gracefully rather than cut desperately mid-task.
+
+### What to cut first
+
+| Content | When to cut |
+|---|---|
+| Past failed attempts and their error output | Once you've moved past them — keep the conclusion, not the journey |
+| Verbose tool output (long `find` results, full file listings) | After you've extracted what you needed |
+| Conversational back-and-forth | As soon as the decision is reached |
+| Earlier drafts of code that were replaced | Immediately on replacement — the current file is the record |
+
+### What to protect until the end
+
+- The original task definition and key constraints
+- The current error message or failing test output you are actively debugging
+- The file currently being edited, or its most recent version
+- Any hard constraints the agent has been asked to enforce (auth rules, naming conventions, etc.)
+
+### Compress before dropping
+
+Summarizing beats deleting. Before removing a long stretch of exploration, reduce it to one sentence capturing the conclusion:
+
+```
+Before: [8 messages debugging a failing import — various attempts, error logs, dead ends]
+After:  "Import issue traced to a circular dependency in src/lib/db.ts —
+         resolved by moving the shared type to src/types/index.ts."
+```
+
+The detail is gone; the decision is preserved. If the detail turns out to matter, the summary is a breadcrumb for re-investigation.
+
+### Order for recency
+
+Put the most task-critical content **last** in context. Models recall content at the start and end of the window more reliably than the middle (the lost-in-the-middle effect — Liu et al., 2023). Keep stable rules and specs at the start; put the active task material last, closest to the generation point:
+
+```
+← session start                              generation point →
+[background: rules, specs, architecture]  [working: current file, error, task]
+```
+
 ## MCP Integrations
 
 For richer context, use Model Context Protocol servers:
@@ -260,6 +305,7 @@ This catches wrong directions before you've built on them. It's a 30-second inve
 | Missing examples | Agent invents a new style instead of following yours | Include one example of the pattern to follow |
 | Implicit knowledge | Agent doesn't know project-specific rules | Write it down in rules files — if it's not written, it doesn't exist |
 | Silent confusion | Agent guesses when it should ask | Surface ambiguity explicitly using the confusion management patterns above |
+| Context cliff | Waiting until the window is full before managing it — attention fragments and output quality drops abruptly at the limit | Start trimming at 75% capacity; compress rather than cut |
 
 ## Common Rationalizations
 
@@ -275,7 +321,7 @@ This catches wrong directions before you've built on them. It's a 30-second inve
 - Agent output doesn't match project conventions
 - Agent invents APIs or imports that don't exist
 - Agent re-implements utilities that already exist in the codebase
-- Agent quality degrades as the conversation gets longer
+- Agent quality degrades mid-task as the conversation grows — failed attempts, replaced drafts, and verbose tool output are not being trimmed
 - No rules file exists in the project
 - External data files or config treated as trusted instructions without verification
 
@@ -287,3 +333,5 @@ After setting up context, confirm:
 - [ ] Agent output follows the patterns shown in the rules file
 - [ ] Agent references actual project files and APIs (not hallucinated ones)
 - [ ] Context is refreshed when switching between major tasks
+- [ ] During long sessions, context is actively managed: failed attempts and replaced drafts removed, live error and task definition protected
+- [ ] Task-critical content (current error, active constraint) is positioned last in context, not buried under background material