context-health

Recognizes and prevents context window degradation — poisoning, distraction, confusion, and clash failure modes. Use when context seems stale, when agent behavior degrades mid-session, or when building context-aware systems.

Model	Source
sonnet	pack: context-engineering

Full Reference

context-health

Announcement

┏━ 🧠 context-health ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ your friendly armadillo is here to serve you ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Diagnoses and prevents context window degradation. Context is a finite, depletable resource — once poisoned or exhausted, quality collapses silently.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

The Four Failure Modes

See reference/failure-modes.md for full examples and symptoms.

Mode	Root Cause	Primary Signal
Poisoning	Bad output fed back as ground truth	Hallucinations compound across turns
Distraction	High-salience irrelevant content	Agent fixates on wrong files/concepts
Confusion	Semantically similar but unrelated info	Subtle cross-domain bleed
Clash	Accumulated contradictions	Flip-flopping, inconsistent decisions

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Symptoms Checklist

Run this checklist when behavior feels off mid-session:

Poisoning signals:

• Agent cites earlier output as external fact
• Confidence increases while accuracy decreases
• Error messages from previous steps appear as valid data

Distraction signals:

• Agent keeps referencing a file that isn’t relevant to current task
• Large pasted block (log, schema, diff) dominates all subsequent reasoning
• Responses reference context from 10+ turns ago unprompted

Confusion signals:

• Domain terminology bleeds across subsystems (e.g., “user” meaning two different things)
• Agent applies patterns from one layer to another (e.g., DB schema rules to API design)
• Similar variable names cause wrong-file edits

Clash signals:

• Contradictory decisions made within the same session
• Agent re-debates settled questions
• Implementation diverges from earlier agreed architecture

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Prevention Patterns

See reference/prevention-patterns.md for implementation detail.

Progressive Disclosure

Load context incrementally — only what the current task requires. Never dump entire files unless they are directly acted upon.

Wrong:  Read all 12 files → then ask question
Right:  Ask question → read only files needed to answer it

Token Budgeting

Assign explicit token budgets per context zone:

Zone	Budget	Policy
System prompt	~2k tokens	Fixed — skills, rules, identity
Working memory	~4k tokens	Rotating — current task only
Evidence	~8k tokens	Scoped — file excerpts, not full files
History	Remainder	Compressed via artifacts

When approaching limits, offload to artifacts before the window fills. Waiting until 95% means the offload itself gets truncated.

Strategic Offloading

Before context fills:

1. Write decisions to .claude/progress/ or a task-specific artifact
2. Summarize completed work into a compact handoff note
3. Start fresh context with the handoff note as input — not the full history

Observation Masking

Tool outputs that are high-volume and low-signal (test run logs, full diffs, raw API responses) should be summarized before being returned to the main context.

Wrong:  Return full 800-line test output to context
Right:  Extract: pass/fail counts + failing test names + first error per failure

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Recovery Actions

When degradation is detected, take the appropriate recovery action:

Detected Mode	Immediate Action	Then
Poisoning	Stop. State what was hallucinated and which turn introduced it	Re-run from last verified checkpoint
Distraction	Explicitly name the distractor and exclude it from scope	Restate the actual task goal
Confusion	Define the conflicting terms with explicit namespacing	Audit recent edits for cross-contamination
Clash	Surface all contradictory decisions explicitly	Re-decide from first principles, write to artifact

Nuclear option: /compact the session, then resume with a clean handoff artifact. Don’t try to correct a heavily degraded context in-place — the corrections themselves become noise.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Integration with verification-before-completion

Before claiming any work is complete, run the context probe gate:

1. Poisoning probe — Can you trace every factual claim to an external source, not a previous model output?
2. Distraction probe — Does the implementation address the original task, not a distractor?
3. Confusion probe — Are all domain terms used consistently across modified files?
4. Clash probe — Do all decisions in this session form a coherent, non-contradictory whole?

If any probe fails, invoke systematic-debugging before committing. A context health failure is a category of bug — treat it as one.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

When to Invoke This Skill

Trigger	Action
Agent gives confidently wrong answer	Run poisoning probe immediately
Session > 40 turns	Run full checklist, consider compaction
Agent ignores explicit instruction	Distraction check — identify competing context
Two subsystems get cross-wired	Confusion recovery
Previous decision gets contradicted	Clash recovery + artifact write
Building a multi-agent system	Apply prevention patterns from the start

Reference Files

File	Contents
reference/failure-modes.md	Detailed mode descriptions, examples, symptoms
reference/compression-awareness.md	What survives compaction, artifact trail strategies
reference/prevention-patterns.md	Progressive disclosure, token budgeting, observation masking