From a1c8fa99786082a06c00d99db0de4dbf3dfa3821 Mon Sep 17 00:00:00 2001 From: Arun Kumar Thiagarajan Date: Sun, 2 Aug 2026 08:12:53 +0530 Subject: [PATCH 1/3] docs(context): add Context Budget Management section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds ## Context Budget Management to skills/context-engineering/SKILL.md. The existing skill covers what to load and how to structure it, but has no guidance on what to do as the window fills during a long session — the point where agent quality degrades most visibly in practice. The new section covers: - The 75% threshold: start trimming before the window is full, not after quality has already dropped - Cut-first priority table: failed attempts, verbose tool output, conversational filler, replaced drafts — in order of disposability - Protect-until-the-end list: task definition, active error, current file, hard constraints - Compress before dropping: summarise exploration into one sentence before cutting it — preserves the decision, loses the journey - Order for recency: task-critical content belongs last in context (closest to the generation point), not buried under background loaded at session start Also adds one Anti-Pattern row (context cliff), one Red Flag, and two Verification checkboxes to the existing sections. --- skills/context-engineering/SKILL.md | 47 +++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/skills/context-engineering/SKILL.md b/skills/context-engineering/SKILL.md index be991103..eab5151d 100644 --- a/skills/context-engineering/SKILL.md +++ b/skills/context-engineering/SKILL.md @@ -177,6 +177,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. Transformer attention weights recent tokens more heavily than earlier ones. The active error message or current constraint belongs closer to the generation point than background specs loaded at session start: + +``` +← 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 +303,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 @@ -278,6 +322,7 @@ This catches wrong directions before you've built on them. It's a 30-second inve - Agent quality degrades as the conversation gets longer - No rules file exists in the project - External data files or config treated as trusted instructions without verification +- Agent quality degrades mid-task as the conversation grows and context is not actively managed ## Verification @@ -287,3 +332,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 From cf0ba3fc5dcff629f21a17283acb68ce9270e0b1 Mon Sep 17 00:00:00 2001 From: Arun Kumar Thiagarajan Date: Wed, 5 Aug 2026 21:15:40 +0530 Subject: [PATCH 2/3] =?UTF-8?q?fix(context):=20address=20nucliweb=20review?= =?UTF-8?q?=20=E2=80=94=20merge=20duplicate=20red=20flag,=20wire=20Level?= =?UTF-8?q?=205=20to=20budget=20section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Merge two near-identical red flags ('Agent quality degrades as the conversation gets longer' + 'Agent quality degrades mid-task...') into one sharper line that names what to trim - Add a one-line forward pointer from Level 5: Conversation Management to the Context Budget Management section below, making the brief-intro / full-treatment relationship explicit --- skills/context-engineering/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/context-engineering/SKILL.md b/skills/context-engineering/SKILL.md index eab5151d..46dc0f40 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 @@ -319,10 +321,9 @@ 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 -- Agent quality degrades mid-task as the conversation grows and context is not actively managed ## Verification From cc48b6997eb3d76c1b403826b020299a2eae179f Mon Sep 17 00:00:00 2001 From: Arun Kumar Thiagarajan Date: Sun, 9 Aug 2026 07:23:01 +0530 Subject: [PATCH 3/3] fix(context): correct lost-in-the-middle mechanism per federicobartoli review Replace 'Transformer attention weights recent tokens more heavily' (inaccurate) with the documented U-shaped retrieval effect: models recall content at the start and end of the window more reliably than the middle (Liu et al., 2023). The diagram and rule (active material last) were already correct; only the explanatory sentence was wrong. --- skills/context-engineering/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/context-engineering/SKILL.md b/skills/context-engineering/SKILL.md index 46dc0f40..04718d0b 100644 --- a/skills/context-engineering/SKILL.md +++ b/skills/context-engineering/SKILL.md @@ -215,7 +215,7 @@ The detail is gone; the decision is preserved. If the detail turns out to matter ### Order for recency -Put the most task-critical content **last** in context. Transformer attention weights recent tokens more heavily than earlier ones. The active error message or current constraint belongs closer to the generation point than background specs loaded at session start: +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 →