oimiragieo/context-degradation

Context Degradation Monitor

Detects context window degradation and prescribes corrective actions before accuracy drops.

Severity Zones

Thresholds are expressed as a percentage of the context window budget. For a 200K window, Claude Code's auto-compact fires at ~187K (~93.5%, i.e., contextWindow - 13K).

| Zone | Usage % | ~Tokens (200K) | Status | Action | | ------------ | ------- | -------------- | -------- | --------------------------------------------------------------------------------- | | Green | < 65% | < 130K | Healthy | Normal operation | | Yellow | 65–80% | 130K–160K | Caution | Begin selective compression | | Orange/Red | 80–90% | 160K–180K | Warning | Compress aggressively; summarize completed phases; spawn fresh subagent if needed | | Critical | 90–93% | 180K–186K | Severe | Halt complex reasoning; compress immediately; do not attempt multi-step tasks | | Auto-compact | > 93% | > 186K | Imminent | Claude Code auto-compact will fire; initiate post-compact recovery (see below) |

Reference: Claude Code constant AUTOCOMPACT_BUFFER_TOKENS = 13,000. Auto-compact fires at contextWindow - 13K, so for a 200K window that is 187K (93.5%). "Lost in the middle" effect: middle tokens have 20–40% lower recall past ~100K.

Early Warning Indicators

Symptoms that context degradation is affecting output quality (regardless of token count):

1. Repeated tool calls — Agent re-reads files already read in same session
2. Contradictory reasoning — Later steps contradict earlier decisions
3. Missing prior context — Agent "forgets" task scope or constraints stated at session start
4. Over-explanation — Agent re-explains concepts already established
5. Stale references — Agent references file paths or task IDs that were resolved earlier

If 2+ indicators are present, treat as one zone higher than token count suggests.

Corrective Routing by Zone

Yellow (65–80%):

• Invoke Skill({ skill: 'context-compressor' }) at the current phase boundary
• Remove completed phase content from active context
• Keep: current task spec, key decisions, in-progress file list

Orange/Red (80–90%):

• Invoke Skill({ skill: 'context-compressor' }) — aggressive summarization
• Write phase summary to .claude/context/tmp/phase-summary-{date}.md
• Prune: all resolved task details, intermediate research, superseded plans
• Spawn fresh subagent if remaining work is complex

Critical (90–93%):

• Do NOT continue complex multi-step tasks in current agent
• Spawn a fresh subagent with only the compressed summary as context
• Current agent: write handoff doc → call TaskUpdate(completed) with handoff path in metadata

Auto-compact (>93%):

• Halt immediately
• Write emergency summary: what was done, what remains, key decisions
• Route to session-handoff skill
• Invoke Skill({ skill: 'session-handoff' }) before context window forces truncation
• See Post-Compact Recovery section below for steps after auto-compact fires

Detection Checklist (Run at Each Phase Boundary)

[ ] Usage < 65%?  → Green, no action
[ ] Usage 65–80%? → Yellow, begin compression
[ ] Usage 80–90%? → Orange/Red, compress aggressively
[ ] Usage 90–93%? → Critical, spawn fresh agent
[ ] Usage > 93%?  → Auto-compact imminent; initiate post-compact recovery
[ ] 2+ early warning indicators? → Upgrade one severity zone
[ ] Compression reminder file exists? → Invoke context-compressor immediately

Post-Compact Recovery

When Claude Code's auto-compact fires (or a microcompact is detected), the context has been silently truncated. Follow these steps to restore working state:

1. Re-read active files — Read all files from the pre-compact snapshot's activeFiles list (stored in .claude/context/runtime/pre-compact-snapshot.json). This restores the in-memory view of code you were editing.
2. Verify task state — Read .claude/context/runtime/edit-counter.json and current task files to confirm what was completed before compaction and what remains.
3. Check for microcompact indicators — Look for a microcompact-detected event in the flight recorder (.claude/context/runtime/flight-recorder.jsonl). If present, a silent compaction occurred without a PreCompact hook event; treat your current context as potentially incomplete.
4. Reference the pre-compact snapshot — Load .claude/context/runtime/pre-compact-snapshot.json to recover originalIntent, editCount, correctionCount, and the list of activeFiles written just before compaction.
5. Re-invoke your current skill — If you were mid-skill when compaction fired, invoke the skill again so its procedures are in context before continuing work.

These steps ensure that after a compaction event (auto or silent), you resume with full knowledge of where you left off.

Integration

• Pairs with: context-compressor, context-compressor, session-handoff
• Called by: planner (at plan start), developer (after each phase), router (before large spawns)
• Trigger: Check at every phase boundary, not just when problems appear

Iron Laws

1. ALWAYS check token count at every phase boundary — not just when problems appear or after completing a large task.
2. NEVER continue complex multi-step tasks past 90% usage (Critical zone) in the same agent context — spawn a fresh subagent with a compressed handoff instead.
3. ALWAYS treat 2+ early warning indicators as one severity zone higher than the raw usage percentage suggests.
4. ALWAYS invoke context-compressor at Yellow zone (65–80%) before context bloat becomes severe — prevention is cheaper than recovery.
5. NEVER claim a task complete without writing a context summary when operating in Critical or Auto-compact zone — if it's not written down, the next agent won't know it happened.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | Waiting until output quality degrades before checking context | By the time quality drops, the context is already in Red/Critical zone | Run detection checklist at every phase boundary proactively | | Continuing multi-step tasks past 90% usage (Critical zone) | "Lost in the middle" effect causes 20–40% recall drop; decisions made early are forgotten | Spawn fresh subagent at Critical zone (90%) with compressed context | | Ignoring early warning indicators because token count looks fine | Indicators are more reliable than raw token counts; a 30K session with 3 indicators is already Yellow | Treat 2+ indicators as one zone higher regardless of token count | | Spawning a subagent without a written handoff document | Subagent starts from scratch, duplicating work or missing constraints | Always write phase summary to .claude/context/tmp/ before spawning | | Compressing context by deleting tool call results without summarizing | Compression without summarization loses critical findings from earlier phases | Summarize completed phase outputs before pruning raw tool results |

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.