Docs › Skills › Context Hygiene

Context Hygiene

/clear discipline and context management for long research sessions. Prevent degradation before it starts.

Why This Matters

Claude degrades with long context. Responses become less precise, more generic, and more likely to hallucinate details. Research sessions with investigation, implementation, and debugging can easily exceed the threshold where degradation kicks in. This skill enforces the discipline of clearing context proactively — before quality drops.

Don't Wait for Degradation

By the time responses feel "off", significant context quality has already been lost. The README IS the memory — everything that matters must be written down before clearing.

When It Activates

Trigger	Details
Auto	Conversation exceeds ~15 substantive turns (not counting short confirmations)
User trigger	"getting long", "context is large", "should I clear", "running out of context"
Post-implementation	After completing a major component or reaching a pause point in the plan

Pre-Clear Checklist

Before clearing, ensure ALL of the following are complete:

1. Update the Living README

Is the investigation README in scratch/ up to date with current findings?
Are all design decisions documented?
Is the plan status updated (which tasks are done)?

"Let me update the investigation README with our current
progress before we clear."

2. Capture a Retrospective

If any of the following are true, capture a retrospective before clearing:

Were experiments run this session?
Were bugs found and fixed?
Were there failed attempts worth documenting?

"We should capture a retrospective before clearing — the
failed attempts table won't survive a context reset."

3. Archive the Session

Suggest session archival via propel-session save or /new-session. If a session was started with propel-session launch, remind the user that chat history will be saved on exit.

4. Note Where to Resume

Write a clear "Next Steps" section in the investigation README. Include what to do next, which plan tasks remain, and any open questions.

"I've added a 'Next Steps' section to the README. When you
resume, start by reading scratch/{investigation}/README.md."

Recovery After Clearing

When the session resumes (the session-start hook re-fires):

Read the investigation README to restore context
Check scratch/registry/ for relevant entries
Check the plan for incomplete tasks
Continue from where the session left off

Living Documentation Updates

The investigation README is a living document that must be kept current throughout the session. At natural pause points, Context Hygiene proactively suggests updating and clearing:

"We've been going for a while. Good time to update the README
and /clear — context quality degrades in long sessions.
I've updated the README with our current progress."

Retrospectives Are Cheap

5 minutes capturing what was learned saves 30 minutes of repeating failed experiments after /clear. Session archives (chat history + investigation README + retrospective) enable full context recovery for the next session.

Key Principles

Principle	Details
The README IS the memory	Everything that matters must be written down before clearing. Anything not in the README is lost.
Proactive, not reactive	Don't wait for the user to notice degradation. Suggest clearing at natural pause points.
Retrospectives before clearing	The failed attempts table is the most valuable artifact and won't survive a context reset.
Session archives enable continuity	Chat history + investigation README + retrospective = full context recovery.