mfielding92 Context Window Doctor
Diagnose context issues and apply the right fix. Runs in a forked context so the diagnostic itself doesn't pollute the user's session.
Goal
Identify what's causing the user's context problem, apply a specific fix, and confirm the issue is resolved. Done when the user confirms the fix worked or a HANDOFF.md is written for a clean restart.
Process
Step 1: Gather Diagnostics
Ask the user to run /context and share the output (this is a slash command only the user can execute). Also check:
- Current conversation length estimate
- Whether CLAUDE.md exists and its line count
- Number of active skills (description budget usage)
- Whether PROGRESS.md or HANDOFF.md exist
Step 2: Diagnose
Match symptoms to causes:
| Symptom | Likely Cause | Fix |
|---|---|---|
| Ignores CLAUDE.md rules | CLAUDE.md too long or contradictory | Trim under 200 lines, use emphasis on critical rules |
| Forgets earlier instructions | Context full, compaction dropped details | Write to files (PLAN.md, PROGRESS.md), then /compact with focus |
| Repeats itself or circles | Context polluted with failed approaches | After 2 failed corrections, /clear with better prompt |
| Slow or degraded responses | Context near capacity (>60% is caution zone) | /clear if switching tasks, /compact with focus if continuing |
| Unrelated context pollution | Mixed tasks in one session | /clear between unrelated tasks |
| Lost progress after compaction | Important state only in conversation | Dump to PROGRESS.md/HANDOFF.md before next compaction |
CHECKPOINT: Present the diagnosis to the user: detected symptom, likely cause, and proposed fix. Ask: "Does this match what you're experiencing? Should I apply this fix?"
Step 3: Apply Fix
Execute the recommended fix. Common actions:
- Write state to PROGRESS.md or HANDOFF.md
- Suggest user run
/compact [focus instructions]with specific focus - Suggest user run
/clearfor a fresh start - Recommend trimming CLAUDE.md if over 200 lines
Step 4: Verify
After fix is applied, confirm with the user that the issue is resolved.
Prevention Strategies
Offer these proactively:
- Document & Clear: Dump progress to file →
/clear→ start fresh reading that file - Use subagents: Delegate verbose ops (test runs, research, log analysis)
- One task per session:
/clearbetween unrelated work - External state: Plans, specs, progress in files (not just conversation)
- Proactive compaction:
/compact [focus]before auto-compact triggers at ~95% - Lean CLAUDE.md: Under 200 lines. Progressive disclosure for the rest.
Output
Brief diagnosis report: symptom identified, cause, fix applied (or recommended for user to apply). For Emergency Reset cases, confirm HANDOFF.md path.
Emergency Reset
If context is badly polluted:
- Write current state to HANDOFF.md: progress, decisions, next steps, file paths
- Tell user to run
/clear - Tell user: start fresh with "Read HANDOFF.md and continue from where we left off"