diff --git a/skills/context-engineering/SKILL.md b/skills/context-engineering/SKILL.md index be991103..04718d0b 100644 --- a/skills/context-engineering/SKILL.md +++ b/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