Context Window Hygiene skill for Claude Code

The context window is working memory. Output quality drops as it fills with stale exploration, dead-end attempts, and raw logs, long before it is technically full. A hygienic session holds the current goal, the decisions that constrain it, and the relevant code, and keeps everything else on disk where it can be reloaded on purpose.

Tools

Command	Effect	Use when
/context	Shows what is consuming the window (system, tools, MCP, memory, messages)	First step whenever something feels off
/clear	Drops the conversation; starts clean in the same directory	Switching to an unrelated task
/compact [instructions]	Replaces history with a summary, steered by your instructions	Same task, long history, decisions still matter
/rewind (or Esc twice)	Restores an earlier checkpoint of the conversation and/or code	A wrong path was taken; undo it instead of arguing past it
Subagent	Does the noisy work in its own window; returns a summary	Wide searches, log triage, verbose test runs
New session (claude)	Fully fresh start	Context feels poisoned; corrections stop sticking
claude --continue / /resume	Reopen a previous conversation	Picking up work deliberately, not by default

Auto-compact triggers near the limit. Do not let it pick the moment during delicate work; compact or reset yourself at a natural checkpoint.

Decision rules

• New, unrelated task -> /clear. Carrying the previous task’s files and decisions only adds noise.
• Same task, history long, approach settled -> write state to a file, then /compact with explicit keep/drop instructions.
• Last few turns went the wrong way -> /rewind to before the detour. A conversation containing three failed approaches keeps steering toward them.
• Two corrections in a row did not stick, or Claude contradicts a decision made earlier -> the context is polluted. Write the correct state to a file and start a fresh session from it.
• Need to explore something large -> delegate to a subagent (built-in Explore for codebase search) and keep only its summary.
• Approaching auto-compact in the middle of a multi-step change -> finish the current atomic step, update the plan file, then compact.

Workflow for long tasks

- [ ] 1. Check /context at the start; trim fixed costs if large
- [ ] 2. Put the plan in a file (docs/plans/<task>.md or .claude/plans/)
- [ ] 3. Work in steps; after each step, update the plan's status lines
- [ ] 4. Scope every read and command output
- [ ] 5. At checkpoints: compact with instructions, or clear and reload the plan
- [ ] 6. At the end: record outcomes in the plan or a handoff note

1. Trim fixed costs

Everything listed before your first message is paid on every turn:

• MCP servers: each server’s tool definitions sit in context. Disable servers not needed for this repo (/mcp, or remove them from project config).
• Memory files: root CLAUDE.md should be short (see memory-file-architect); large @imports load eagerly.
• Skills: only names and descriptions load up front, but dozens of long descriptions add up.

4. Scope reads and output

Instead of	Do
Reading a 3,000-line file	grep -n for the symbol, then read the relevant line range
Reading every file in a directory	List it, read the 2-3 that matter
Full test suite output	Run the affected tests; quiet reporters; failures only (pytest -q -x, vitest run path --reporter=dot)
cat of a log	tail -n 100, grep -n ERROR, or jq filters
Printing a large JSON API response	`jq ‘.items[]
Pasting a whole stack trace from 5 services	The first error and the deepest frame in project code
Reading lockfiles, build output, minified bundles, snapshots	Do not; query them with grep if needed

Delegate anything whose raw output is large and whose conclusion is small.

5. Compact with instructions

The default summary keeps generalities and loses specifics. Tell it what matters:

/compact Keep: goal (migrate billing to Stripe Payment Intents), decisions (no
backfill; webhook-first), files changed so far, the exact failing test names and
error text, next step (step 5 in docs/plans/billing.md). Drop: exploration of the
legacy PayPal module and the abandoned queue approach.

A CLAUDE.md line such as “When compacting, always preserve the current plan file path, modified files, and failing test names” applies to every compaction, including the automatic one.

Clear-and-reload alternative (often cleaner than compacting):

/clear
Read docs/plans/billing.md. Steps 1-4 are done and committed. Continue with step 5.

Plan file shape

# Billing migration plan
Goal: replace Charges API with Payment Intents; no customer-visible change.
Decisions: webhook-first; idempotency keys per order; no backfill of old charges.
## Steps
- [x] 1. Add PaymentIntent service wrapper (commit a1b2c3)
- [x] 2. Webhook handler for payment_intent.succeeded (commit d4e5f6)
- [ ] 3. Switch checkout to PaymentIntents behind flag `pi_checkout`   <- current
- [ ] 4. Remove Charges code paths
## Facts to keep
- Test webhook secret is in 1Password "stripe-test"; never in code
- `pnpm test:billing` runs the relevant suite in ~40 s

Symptoms of a degraded session

• Re-reading files it already read, or asking for information given earlier.
• Reintroducing a bug that was fixed, or an approach that was rejected.
• Ignoring a constraint stated early in the session.
• Long, meandering answers; slower responses.
• Fixes that oscillate between two wrong versions.

Any two of these: stop, write state to disk, and reset.

Gotchas

• /clear discards everything not written to disk. Save the plan, decisions, and exact error strings first.
• Compaction loses precise details (paths, line numbers, error messages, command flags) unless told to keep them.
• Pasting huge blobs (full logs, whole files, screenshots of text) consumes more than reading a targeted slice with a tool.
• Subagents that return raw dumps move the bloat back into the main thread. Cap their output (see subagent-design).
• Habitually resuming yesterday’s session drags in stale context. Start fresh from a handoff note unless the old conversation is genuinely needed.
• Arguing with a wrong approach for several turns leaves every failed attempt in context. Rewind instead.

Verification

• /context after trimming and after each reset shows messages, not fixed overhead, as the main consumer, and plenty of headroom.
• After a /clear or compaction, Claude can state the goal, the current step, the constraints, and the next action correctly from the plan file alone.
• The same class of mistake does not recur after the reset.

Output

When performing a reset for the user, leave this checkpoint (in the plan file or reply):

**Checkpoint:** before /clear at step 3 of docs/plans/billing.md
**Saved to disk:** plan status updated; failing test `checkout uses payment intent` + error text recorded
**Fixed costs trimmed:** disabled 2 unused MCP servers (-11k tokens); CLAUDE.md imports unchanged
**Resume with:** "Read docs/plans/billing.md and continue with step 3."