| name | context-doctor |
| description | Reduces token waste in Claude Code sessions across two axes — context footprint (auto-generates .claudeignore, guides over-read files and /clear timing) and command output (routes to a command-output proxy/hook such as rtk to trim verbose CLI stdout). In hub environments, regularly audits bloated CLAUDE.md/MEMORY.md/memory/*.md files and proposes compression. Usable standalone without a hub clone. |
| user-invocable | true |
| allowed-tools | ["Read","Write","Bash","Glob","Grep"] |
| model | sonnet |
| complexity_routing | {"base":"sonnet","high":"opus","escalate_when":["cold_start","cross_project"]} |
context-doctor — Token Efficiency Diagnosis + Automatic Prescription
Diagnoses the main causes of session token waste and prescribes immediate remedies:
- No
.claudeignore → unnecessary files loaded wholesale into context
- Repeated full reads of large files → paying the same cost N times
- Not using
/clear after direction changes → continuing work with accumulated noise
- Verbose CLI output → every
git/ls/build/test call floods context with stdout (a different layer from 1–3 — see §Command-Output Reduction)
Two reduction axes — keep them distinct. Causes 1–3 are the context-footprint axis (what gets read into context: files, history). Cause 4 is the command-output axis (tokens produced by the tools you run). .claudeignore cannot touch command output, and a command-output proxy cannot touch file reads — they are complementary, not substitutes.
Standalone install — this skill works normally with plugin install only, without cloning the full meta-harness.
Built-in /doctor first (sister anchor, 2026-07-25): since the Claude 5 generation, the official
/doctor command claims skill/CLAUDE.md rightsizing ("The new rules of context engineering for Claude 5
generation models" — https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models).
Run the built-in first when available — its scope is skills + CLAUDE.md rightsizing only. This skill's
increment over it = .claudeignore diagnosis/generation (Step 1), /clear timing guidance,
command-output proxying (§Command-Output Reduction), hub-wide memory/CLAUDE.md audits, and the
measurement discipline (resident footprint is measured only via a fresh top-level /context, and any
diet is followed by a prompt-regression probe — the blog's own "no measurable loss" claim ships no
method, so treat that number as a vendor claim). Triage record:
tracks/_audit/session_2026_07_25_claude5-context-rules-sister.md.
Execution Steps
Step 1. .claudeignore Diagnosis + Generation
Check whether .claudeignore exists in the project root (bash in §Step-Bash).
If absent: Scan project structure and auto-generate.
If already present: Keep existing content + suggest additional patterns only (no overwrite). Check for sentinel comment (# context-doctor:) and add to first line if absent.
Generation criteria — by project type:
| Detected type | Additional patterns |
|---|
Node.js (package.json) | node_modules/ · dist/ · build/ · .next/ · coverage/ |
Python (pyproject.toml / setup.py) | __pycache__/ · .venv/ · *.egg-info/ · dist/ · .pytest_cache/ |
Java (pom.xml / build.gradle) | target/ · build/ · .gradle/ |
| Common (always include) | .git/ · *.log · *.lock · *.min.js · *.min.css |
Present preview to user after generation → save after confirmation.
Automatically add sentinel comment to first line when generating/updating:
# context-doctor: configured YYYY-MM-DD
→ Suppresses auto-invocation in subsequent sessions.
Detail: See SKILL_detail.md §Step-Bash — detection bash for Steps 1/2/4/5, large-file warning format, audit report format — read when executing any step's commands.
Step 2. Large File Detection + Split Strategy Guidance
Detect files exceeding 500 lines (top 10 — bash in §Step-Bash) and output the split-read guidance per file (offset + limit, section by section).
Repeated full-read pattern (burst pattern) detection criteria (behavioral):
- 3+ files over 500 lines exist and
.claudeignore was absent
- User mentions "read it all at once" / "re-read the whole thing every time"
When burst pattern is detected → trigger harvest-loop integration in Step 4.
Step 3. /clear + Model Switching Timing Guide
Check session state with the user, then prescribe according to context:
Wrap-then-Compact (when approaching context limit — CC subscription only):
When context is near the limit and you want to preserve state rather than reset:
- Ask Claude:
"wrap up — completed items, modified files, pending tasks"
- Claude writes a structured summary → that summary anchors the
/compact output
- Run
/compact — the wrap becomes the cold-start primer for next session
This is superior to blind /compact because you control what's preserved. Bedrock/API has no meter warning — CC subscription only.
→ Full pattern + table: CHEATSHEET.md §10 Lever 6
/clear recommended situations (reset, not preserve):
□ Work direction has changed significantly (exploration → implementation, bug fix → refactor, etc.)
□ Switching to a different track/project
□ Error debugging has gone long and noise has accumulated
□ Previous attempts are unrelated to current work
□ Context has grown large (context rot — measurable quality degradation as input length grows,
well before the window fills; threshold varies by model/task. Chroma 2025 context-rot research)
→ Recommend immediate /clear and restart in fresh context.
Model switching criteria:
| Current task | Recommended | Command |
|---|
| Complex design decisions · architecture review | Opus — dispatch-first: package into an opus/sidecar agent dispatch (consent-gated); session pin secondary | dispatch · or /model opus |
| Code writing · file editing · refactoring | Sonnet (default) | — |
| Simple file lookup · short Q&A | Haiku | /model haiku |
Models are tools for allocating the right expertise to complexity. Opus for simple tasks = wasted expertise; Haiku for design decisions = insufficient expertise. Switch models when task nature changes.
Step 4. harvest-loop Integration (burst pattern recording)
When burst pattern is detected and tracks/_audit/ exists: locate the latest weekly_audit file and suggest adding the Token Efficiency Check items to it (bash + checklist block in §Step-Bash).
Environments without tracks/_audit/ (Mode C — plugin only): → output items to terminal only, skip file writes.
Step 5. CC Context Structure Regular Audit (Hub Environment Only)
Hub environment detection condition: CLAUDE.md contains "your-hub" or "meta hub" + memory/MEMORY.md exists. Skip Step 5 when not in a hub environment.
Run the audit bash (§Step-Bash) and apply thresholds:
| Target | Threshold | Prescription |
|---|
| CLAUDE.md | Exceeds 300 lines | Section-by-section compression / move completed sections to archive |
| MEMORY.md | Exceeds 180 lines | Check entry count + move ✅ CLOSED items to archive section |
| memory/*.md single file | Exceeds 30K (300 lines) | Suggest splitting accumulated history into separate files |
| SKILL.md (any) | > 300 lines AND no SKILL_detail.md | Propose /salience-splitter — governance-semantic split (not compression); compression removes content, splitting routes it on-demand |
Frequency: When explicitly called with /context-doctor or auto-invoked at session start when MEMORY.md is detected at 180+ lines.
Context Hierarchy (L1/L2/L3)
Information buried in the middle of a long context window suffers measurable accuracy loss — the "lost in the middle" effect, ~10–30% degradation for mid-context information (see ../../../../knowledge/shared/harness-core/harness_frontier_diagnosis_2026-06-02.md). The remedy is two-fold: tier the context, and place the most important instructions at the start and end, never buried in the middle.
Three tiers — keep each within its band:
| Tier | What lives here | Rough budget | FH example |
|---|
| L1 — always-on | System / critical instructions that must hold every turn | ~2–5K tokens | CLAUDE.md core rules, active session.md header |
| L2 — session summary | Current task state, decisions made this session | ~5–20K tokens | active track session file, reference_next_session_starter.md |
| L3 — on-demand | Reference material retrieved only when needed | unbounded, loaded then dropped | knowledge/ docs, large source files via Read offset/limit |
Placement norm (applies to CLAUDE.md, prompts, and dispatched Context Cards):
- Put the load-bearing rule or task goal in the first lines and restate it in the last lines.
- Do not park a critical constraint in the middle of a long document — it is the most likely place to be missed.
- Promote frequently-needed L3 docs to L2 summaries; demote stale L1/L2 content to L3 (load on demand) rather than keeping it always-on.
When auditing CLAUDE.md / MEMORY.md in Step 5, check tier placement too: a critical rule sitting mid-file is a placement defect even if the file is within its line budget.
Measured anchor — select what to feed back, don't truncate at overflow. Less Context, Better Agents (arXiv:2606.10209) measures this: pruning the fed-back context to the last 5 tool-call/response pairs raises complete itemization to 79.0% (vs 71.0% keeping full history, 8.0% naive truncation) while cutting total token use to 535,274; adding summarization reaches 91.6%. Evidence that selective retention beats a blind /compact or overflow truncation — measured on agent tool-call history (a runtime analogue of the L1/L2/L3 tiering above, not a direct test of it).
Compression Pass
Optional step, run when context is large (e.g. after Step 5 flags a bloated file, or an L3 doc is long but must be loaded). This goes beyond .claudeignore — .claudeignore blocks files from loading; compression shrinks content that does need to load. LLMLingua-style compression is reported to reach ~100K→20K token reductions with minimal loss on long retrieved context (see ../../../../knowledge/shared/harness-core/harness_frontier_diagnosis_2026-06-02.md Provenance).
Advisory and tool-agnostic — recommend (and, where a doc is being authored/edited in-session, apply) these reductions:
- Strip boilerplate: repeated headers/footers, navigation, license blocks, generated banners.
- Collapse repeated or near-duplicate sections into a single canonical statement plus a pointer.
- Summarize long retrieved docs to the task-relevant slice before pinning them into context; keep the full doc as an L3 file to re-read only if needed.
- Prefer Read offset/limit over full-file reads for large files (ties back to Step 2).
Keep it reversible: compress the working copy in context, not the source of truth on disk, unless the user is explicitly editing that file.
Detail: See SKILL_detail.md §Headroom — external tooling option (redundancy-category targeting, integration surfaces, caveats) — read when executing a compression pass and considering tooling.
Command-Output Reduction (the command-output axis)
The reductions above all act on the context-footprint axis (files, history read into context). They do nothing for the command-output axis: the stdout of every shell call. A single git log, npm test, ls -R, or build run can dump thousands of tokens per call, and an agent makes dozens of calls per session — often the largest single token sink, and invisible to .claudeignore.
This axis is risk-gated — reduce it only when token cost is the binding constraint. Unlike .claudeignore (which blocks provably-irrelevant files — near-lossless and reversible), command-output reduction works by filtering live output, which is lossy by design: a dropped middle line — an error inside build output, one file in a long listing — is invisible to the agent, which cannot know what it did not see. So the default is to do nothing here. Turn it on only in a genuinely token-scarce setting (a metered / quota-limited backend where token budget is the binding constraint — not where tokens are merely plentiful); there the savings outweigh the information-loss risk, and everywhere else they do not.
Two ways to reduce, safest first:
- Per-call narrow flags (default — non-lossy, no install). Prefer narrow commands:
git log --oneline -N over bare git log, --quiet on noisy tools, head/tail on long output. The agent chooses what to drop, per call — no blind heuristic. This suffices for almost every session.
- A command-output proxy/hook (only under token scarcity). A Claude Code hook that rewrites verbose commands through a token-reducing proxy, transparent (0 prompt-side overhead). Recommended tool:
rtk (Rust Token Killer), a CLI proxy that filters dev-command output (the tool reports ~60–90% savings on dev operations), wired so git status → rtk git status happens automatically.
- ⚠️ Name collision: there is an unrelated
reachingforthejack/rtk (Rust Type Kit). Verify the Token-Killer build — rtk gain (savings analytics) should work; "command not found" means the wrong binary.
- No-reinvention: FH routes to this tool; it does not rebuild a token-killer. Install + hook wiring live in the user's own config (global
CLAUDE.md / settings.json), never reimplemented here.
- ⚠️ Never filter a command whose output a mechanical gate parses. FH gates read raw command output (a pre-commit hook greps,
regression_guard diffs). A filtered git diff / git log feeding a gate gives the gate wrong input — the same trap as grepping filtered prose for a verdict (typed-verdict-channel). Keep filtering off gate-input paths, and keep a raw escape hatch (rtk proxy <cmd>).
Prescription: in a normal token environment, recommend the per-call flags (#1) and do not suggest installing a proxy — the lossy risk is not worth it. Only when the user states or exhibits a binding token constraint, surface #2 with the gate-input caveat above. Diagnosis + recommendation, never an auto-install.
External User Environment Adaptation
| Environment | Behavior |
|---|
| Meta-harness cloned (Mode A) | Perform full Steps 1–5 / integrate with harvest-loop files |
| Plugin only (Mode C) | Perform Steps 1–3 / Step 4 output only (no file writes) |
| External general environment | Focus on .claudeignore generation + large file guidance |
Invocation Triggers
Auto-Invocation Conditions (at session start)
Invokes only when .claudeignore is absent:
"This project has no .claudeignore. Token waste may be occurring. Check with /context-doctor?"
When .claudeignore exists → skip auto-invocation (treated as already configured).
Burst pattern auto-detection (500+ line files) is excluded from auto-invocation — only performs on explicit call. Firing every session becomes noise.
Suppress Mechanism
context-doctor adds a sentinel comment to the first line when generating or updating .claudeignore:
# context-doctor: configured 2026-05-10
Auto-invocation decision order:
.claudeignore absent → auto-invoke O.claudeignore present + sentinel present → auto-invoke X (fully suppressed).claudeignore present + sentinel absent (manually written) → auto-invoke X (file existence itself is suppress signal)
Manual suppress: User adds the following to the first line of .claudeignore for permanent suppress:
# context-doctor: suppress
Explicit invocation (/context-doctor) always runs regardless of suppress state.
Explicit Triggers
/context-doctor- "token waste", "session is slow", "reading the whole file", "claudeignore", "context cleanup"
- "context diet", "memory audit", "CLAUDE.md is heavy", "MEMORY.md size"
- "context engineering", "context rot", "context collapse"
- "command output is huge", "verbose output", "rtk", "token killer", "trim command output"
Natural Language Triggers (activates without internal vocabulary)
Also activates when an external user expresses without token/context terminology:
| Example utterance | Intent | Mapped diagnosis |
|---|
| "The context seems to be getting too large" | Suspected context bloat | Step 5 (hub) / Step 2 |
| "Tokens are being wasted" | Suspected token efficiency degradation | Step 1 + Step 2 |
| "The conversation feels inefficient" | Suspected accumulated session noise | Step 3 (/clear timing) |
| "Why is Claude so slow?" | Burst pattern or context overload | Step 2 |
| "Seems like it keeps re-reading the same thing" | Repeated full-read detected | Step 2 (burst pattern) |
| "Answers get weird as the session gets longer" | Accumulated context noise | Step 3 (/clear recommended) |
| "Context is getting full", "context meter is high" | Approaching context limit | Step 3 — propose Wrap-then-Compact pattern |
| "context engineering", "doing context engineering", "context rot setting in" | 2026 industry term for context discipline (Chroma 2025 / Anthropic) | Step 2 + Step 3 |
| "every git command dumps a wall of text", "the build output eats my context" | Verbose command output flooding context | §Command-Output Reduction (route to proxy/hook) |
Three-Doctor Loop Integration
context-doctor's Role in Three-Doctor Loop
harness-doctor → current skeleton diagnosis "Is the structure correct? Any drift/complexity/broken references?"
context-doctor → current context diagnosis "Is Context Collapse occurring?"
sim-conductor → future behavior prediction "What happens when a real person uses this system?"
context-doctor is the current context diagnostic role among the three skills. It detects token waste/burst patterns/context contamination and presents prescriptions (.claudeignore/clear timing), which harness-doctor (skeleton) and sim-conductor (future behavior) then pick up to complete the closed loop.
Context Anxiety: Agents make uncertain inferences when relevant context is absent — this is the engineering rationale behind the context-doctor/bridge structure. (Anthropic official naming 2025)
context-doctor (token/context) · harness-doctor (structure) · sim-conductor (simulation/ideation) — the three skills form a diagnosis→prescription→re-diagnosis closed loop.
| Situation | Next skill |
|---|
| Want to also check structure after resolving token waste | /harness-doctor |
| Want to validate prescription results from external user perspective | /sim-conductor Area A |
| SKILL.md diagnosed as over-loaded (> 300 lines, no SKILL_detail.md) | /salience-splitter — governance-semantic split |
| All three skills mentioned simultaneously | Three-Doctor Loop circuit activated — diagnosis→prescription→re-diagnosis cycle |
Done When
| Condition | Completion verdict |
|---|
| Diagnosis results output to conversation (relevant stages among Steps 1~5) | ✅ Diagnosis complete |
.claudeignore created or modified + path output | ✅ Prescription complete |
| Large file detected with split strategy guidance output | ✅ Step 2 complete |
| "No context structure issues" judgment output | ✅ Health check complete |
This skill's Done When = "diagnosis report output complete". Actual resolution of prescription items is in the user's or follow-up work domain and is not included in this skill's completion criteria.
External validation path: harvest-loop Step 3.75 Critic isolated Agent can independently judge against the above criteria (skill_quality_rubric.md verifiable criteria). Automatically linked when subsequent steel-quench runs.
→ Three-Doctor Loop chain (auto-propose after diagnosis):
- Prescription modifies SKILL.md / rules / CLAUDE.md → propose
/harness-doctor re-check after fix (structural integrity)
- Prescription addresses user-facing context (onboarding, README, install guides) → propose
/sim-conductor Area A (external user impact validation)
- SKILL.md detected as over-loaded → auto-propose
/salience-splitter: "I see [skill-name] SKILL.md is [N] lines with no SKILL_detail.md. Want me to run /salience-splitter to do a governance-semantic split?"
