# Context & Session Management

Effective context management is critical for AI coding assistant performance. Apply these patterns automatically.

## Thinking Modes

AI coding assistants support different thinking depths. Use the appropriate mode for the task:

| Mode | Effort | When to Use |
|------|--------|-------------|
| Light | ~4k tokens | Simple tasks, quick fixes, routine operations |
| Medium | ~8k tokens | Moderate complexity, single-file changes |
| Deep | ~16k tokens | Multi-file changes, architectural decisions |
| Maximum | ~32k tokens | Complex problems, deep analysis, novel solutions |

### Mode Selection Guidelines

**Light thinking for:**
- Bug fixes with obvious solutions
- Adding simple functions
- Documentation updates
- Routine git operations

**Medium thinking for:**
- Implementing defined features
- Code review of single files
- Debugging with clear symptoms
- Refactoring within a module

**Deep thinking for:**
- Features touching multiple files
- Debugging with unclear root cause
- API design decisions
- Integration work

**Maximum thinking for:**
- Architectural planning
- Complex algorithm design
- Unfamiliar codebases (initial exploration)
- Multi-system integration
- Research synthesis

## Context Budget Awareness

### Understanding Your Budget

AI assistant context windows are NOT all available for work:

| Component | Approximate Tokens | Notes |
|-----------|-------------------|-------|
| Tool definitions | ~25-30k | Loaded at startup |
| Auto-loaded rules | ~3-5k | From `.claude/rules/` |
| Plugins | ~3-5k | If installed |
| CLAUDE.md | ~1-2k | Project instructions |
| **Startup overhead** | **~35-45k** | Before any work begins |
| **Working context** | **~125-165k** | What's actually available |

### When Quality Degrades

Quality degradation is **gradual**, not a cliff. Watch for these symptoms:
- Forgetting earlier instructions
- Repeating previously rejected approaches
- Missing obvious connections between files
- Declining code quality
- Ignoring established patterns

### Fresh Session vs Compacting

| Situation | Recommendation |
|-----------|----------------|
| Iterative refinement of same feature | Let it compact, continuity helps |
| Switching to unrelated task | Fresh session |
| Quality noticeably declining | Fresh session |
| Deep in complex debugging | Let it compact, context is valuable |
| After completing major milestone | Fresh session (clean slate) |
| AI contradicting itself | Fresh session |

**Key principle:** Important context should live in files, not just conversation history. If you've been writing decisions to CLAUDE.md, task notes, and code to files, then a fresh session can reload what matters.

### Execution Readiness Check

**Before starting implementation of 3+ tasks, verify context budget.**

| Context Used | Action |
|-------------|--------|
| < 70% | Proceed with implementation |
| 70-80% | Ask: "We have N tasks remaining and context is at ~X%. Proceed now or defer to a fresh session?" |
| > 80% | Default to deferring. Commit current work, create handoff doc, start fresh. |

**Why this exists:** At high context usage, quality degrades gradually -- forgotten instructions, repeated mistakes, missed connections. Starting multi-task execution late in a session risks compounding errors.

## Persistence Strategy

Don't rely on conversation history for important context.

| Context Type | Where to Persist | When Loaded |
|--------------|-----------------|-------------|
| Project patterns, constraints | CLAUDE.md | Every session |
| Architectural decisions | `docs/decisions/*.md` | On demand |
| Current task learnings | Task notes/descriptions | With task |
| Session discoveries | SESSION.md or work log | On demand |
| Pre-compaction state | `.claude/sessions/` | On session start |
| Code rationale | Code comments | With file |

```
Good: Add stable project patterns to CLAUDE.md (sparingly)
Good: Create docs/decisions/YYYY-MM-DD-topic.md for ADRs
Good: Put "why" comments in code

Bad: Dump session notes into CLAUDE.md (bloats startup)
Bad: Assume the AI remembers 30 messages ago
Bad: Reference "what we discussed earlier" without specifics
```

**CLAUDE.md should stay lean** -- it's loaded every session. Use it for stable, long-term project context only.

## Sub-Agent Best Practices

Sub-agents get fresh context windows. Use them for:

| Task Type | Use Sub-Agent? | Why |
|-----------|----------------|-----|
| Isolated research | Yes | Fresh context, focused scope |
| Code review | Yes | Independent perspective |
| Validation/testing | Yes (blind) | Unbiased verification |
| Multi-step implementation | Sometimes | Break at natural boundaries |
| Quick fixes | No | Overhead not worth it |

**Blind Validator Pattern**: For testing, spawn a separate agent that only sees test results, not the implementation. This prevents bias in verification.

## Token-Conscious Habits

1. **Read selectively**: Use line limits when reading large files
2. **Summarize findings**: Don't paste entire files into responses
3. **Use project indexes**: Reference structure, not full content
4. **Tier documentation lookups**: Knowledge -> lightweight fetch -> heavy docs
5. **Clear completed context**: Start fresh after major milestones

## Quick Reference

```
Context feeling sluggish?
|-- Quality actually declining? (forgetting, contradicting, poor output)
|   |-- Yes, same task: Spawn sub-agent for fresh perspective
|   |-- Yes, new task: Start fresh session
|   |-- No, just anxious: Continue working
|
|-- Switching task domains?
|   |-- Related work: Continue
|   |-- Completely different: Fresh session
|
|-- Major milestone complete?
|   |-- Natural breakpoint: Good time for fresh session
|
|-- About to execute 3+ tasks?
    |-- Context < 70%: Proceed
    |-- Context 70-80%: Ask user
    |-- Context > 80%: Handoff doc + fresh session
```