session-context-management

# Session Context Management **Auto-activate when:** Working with `CURRENT.md`, `STATUS.md`, `LESSONS.md`, `.session/` directory, or when user mentions /snapshot, /pickup, resume, session, or context management. **Purpose**: Maintain "just enough" context across work sessions for resuming non-trivial development tasks **Philosophy**: Document to resume work, not to create archives. Tokens aren't free. Err on side of less. --- ## When to Activate **Activate this skill when ANY of these are true:** 1. **Task duration**: Work will take more than 15 minutes 2. **Multiple files/steps**: Work touches 3+ files OR has 3+ distinct steps 3. **Interruptions likely**: Meeting soon, end of day approaching, or working on unfamiliar code 4. **Scope might expand**: Starting with "just a quick fix" on complex code 5. **User explicitly invokes `/snapshot` or `/pickup` commands** **Default rule**: If unsure whether to activate → activate (overhead is minimal). **Do NOT activate for**: Single file edits under 10 minutes, trivial tasks, purely informational requests. --- ## Core Principles & Anti-Patterns **✅ Do:** - "Just Enough" > Complete - Document to resume, not archive - Tokens Aren't Free - Every line costs tokens - User Can Fill Gaps - They remember context better than docs - Err on Side of Less - Add detail only when painful without it - ADHD-Friendly - Interruptions and rabbit holes are normal - Walk Away Anytime - Never lose context mid-work **❌ Don't:** - Complete audit trails - Not an archive - Explaining obvious things - User knows context - Upfront planning - Document as you go - Perfect grammar - Bullets > prose - Waiting for session end - Update continuously - Rigid templates - Adapt to needs --- ## Security Rules (BLOCKING) **CRITICAL: Validate content before writing session files** Before writing to CURRENT.md, STATUS.md, or LESSONS.md, scan content for sensitive data. If detected, REFUSE to write and warn user. ### Prohibited Patterns (BLOCK & REFUSE): - API keys: API_KEY=, sk-ant-, sk-proj-, ANTHROPIC_API_KEY= - Passwords: PASSWORD=, pwd=, passwd=, password: - Tokens: TOKEN=, Bearer, token:, access_token= - Private keys: -----BEGIN PRIVATE KEY-----, -----BEGIN RSA - Credentials: connection strings with passwords, username/password pairs - PII: SSN, credit cards, personal email addresses in creds - CUI: classified info, proprietary secrets ### Safe Content (ALLOW): - Timestamps: 2025-01-13 14:30 - Task descriptions: "Implement login", "Fix auth bug" - Test results: "3 pass, 1 fail", "Coverage 85%" - Status: "Blocked on API", "Waiting for review" - Patterns: "Use uv run python", "Prefer Edit over Write" - File paths: ALWAYS use relative paths (src/auth/login.py) NEVER absolute paths (C:\Users\...) ### Validation Process: 1. Review entire content block before writing 2. Check for prohibited patterns 3. If found: STOP, show detected content, refuse to write 4. If clean: Proceed with write --- ## Low Context Warning Protocol **Automatic Monitoring**: Check token budget in `<system-reminder>` tags throughout conversation. **When < 10% Remaining (~<20k tokens):** 1. Capture snapshot immediately using CURRENT.md format 2. Alert user: "⚠️ Context usage at [X%] ([used]/[total] tokens). Recommend `/clear` soon to avoid interruption." 3. Provide resume prompt: ``` Copy this to resume after /clear: Resume [feature-name]: [Right Now from CURRENT.md] Last done: [Last item from Done list] Next: [Next 3 #1] [Blockers if any] ``` **When < 5% Remaining (~<10k tokens):** 1. Urgent snapshot capture 2. Strong warning: "🚨 Context critical - [remaining] tokens left. `/clear` now recommended to avoid interruption." 3. Provide ready-to-use resume prompt **Why this approach**: No waiting for context compaction, seamless continuation, user control, preserves work. --- ## File Structure ``` project-root/ └── .session/feature/[feature-name]/ ├── CURRENT.md # 🚀 READ FIRST - Quick resume (~150 lines max, includes Feature Overview) ├── STATUS.md # 📋 Terse log - Chronological entries with discussion capture └── LESSONS.md # 💡 Bullet points - What worked/didn't ``` **Why `.session/`**: Usually gitignored (working memory, not documentation), UNLESS project has `enable-session-commits: true` **Why `feature/[feature-name]/`**: Separate contexts for different work streams **CURRENT.md structure**: Feature Overview (slower-changing 50,000-foot view) + session work state (faster-changing tasks/progress) --- ## Multi-Instance Support **Scenario**: Multiple Claude instances working on same feature simultaneously **Solution**: Tagged sections in single files using `[instance-id:session-id]` format ### Instance/Session ID Detection **Instance ID** (which IDE window): ```bash INSTANCE_ID=$(cat ~/.claude/ide/$CLAUDE_CODE_SSE_PORT.lock 2>/dev/null | python -c "import json, sys; print(json.load(sys.stdin)['authToken'][:8])" 2>/dev/null || echo "unknown") ``` **Session ID** (which conversation): ```bash SESSION_ID=$(ls -lt ~/.claude/debug/*.txt 2>/dev/null | head -1 | awk '{print $9}' | xargs basename 2>/dev/null | cut -d. -f1 | cut -c1-8 || echo "unknown") ``` **Combined Tag**: `[$INSTANCE_ID:$SESSION_ID]` (e.g., `[5d72a497:888cf413]`) ### File Format with Multiple Instances **CURRENT.md** (shared Feature Overview + separate sections per instance): ```markdown # [Feature Name] - Current State ## Feature Overview **Goal**: High-level description of what this feature accomplishes and why it's needed **Key Requirements**: - Critical constraints or dependencies **User Stories**: - Specific use cases or scenarios **Design Decisions**: - Architectural choices made and their rationale --- ## [5d72a497:888cf413] Frontend Queue Last: 2025-11-13 23:30 ### Right Now Working on queueing multiple questions without waiting ### Last 5 Done 1. ✅ Implemented queue system ... --- ## [a08428d4:3e5380bd] Transcripts Last: 2025-11-13 23:28 ### Right Now Adding timestamp support to archive format ### Last 5 Done 1. ✅ Fixed quotes escaping ... ``` **STATUS.md** (tagged entries with discussion capture): ```markdown # Status Log --- ## [5d72a497:888cf413] 2025-11-13 23:30 - Queue system **User Request**: Enable submitting multiple questions without blocking **Discussion**: Chose client-side queue over server queue for simpler implementation **Outcomes**: ✅ Frontend can queue multiple questions ❌ No concurrent request handling yet **Next**: Test concurrent requests --- ## [a08428d4:3e5380bd] 2025-11-13 23:28 - Transcript timestamps **User Request**: Add timing information to transcripts **Discussion**: Archive format needs extension for metadata **Outcomes**: ❌ Timestamps not in archive format **Next**: Add timing metadata ``` **LESSONS.md** (shared, no tags): - No instance tags - shared learnings across all instances working on feature ### Behavior - Each `/snapshot` updates or creates its own `[instance:session]` section - Other instances' sections preserved - `/pickup` shows all instances for all features - Single source of truth per feature, multiple contexts visible --- ## File Format Templates **CRITICAL: Use Relative Paths Only** When writing file paths in session files, ALWAYS use relative paths from the feature's working directory: - ✅ GOOD: `frontend/src/routes/+page.svelte`, `api/main.py`, `docker-compose.yml` - ❌ BAD: `C:\Projects\agent-spike\projects\mentat\api\main.py`, `projects/mentat/frontend/src/...` - ❌ BAD: `/home/user/code/app/main.py` **Rationale**: - Session files may be shared or moved - Absolute paths expose system details and break portability - Paths relative to feature directory are most natural when working in that context - Example: `.session/feature/mentat/` should use `api/main.py` not `projects/mentat/api/main.py` --- ### CURRENT.md - Quick Resume with Feature Overview **Purpose**: Resume work in < 2 minutes | **Max Size**: ~150 lines | **Update**: After milestones (~1-2 hours work) **Structure**: Feature Overview (slower-changing) at top, session work state (faster-changing) below ```markdown # [Feature Name] - Current State ## Feature Overview **Goal**: [What this feature accomplishes and why it's needed - 50,000-foot view] **Key Requirements**: - [Critical constraints, dependencies, or technical requirements] - [Another key requirement] **User Stories**: - [Specific use case or user scenario] - [Another user story] **Design Decisions**: - [Architectural choice made]: [Rationale] - [Another design decision]: [Why this approach] --- ## [instance-id:session-id] [Session Title] Last: YYYY-MM-DD HH:MM ### Right Now [One sentence describing what you're doing RIGHT NOW] ### Last 5 Done 1. ✅ [Most recent completed task] 2. ✅ [Previous completed task] 3. ✅ [Earlier completed task] 4. ✅ [Earlier completed task] 5. ✅ [Earliest completed task] ### In Progress [If TodoWrite active: Copy active todos here] [If no TodoWrite: List what's being worked on from context] - [Active item 1] - [Active item 2] ### Paused [Leave empty UNLESS you context-switched to different feature] [If paused items exist: "- [Feature name] - [Why paused]"] ### Tests [If tests were run, show results. If not run yet, write "Not run yet"] **[Framework name]**: X pass / Y fail - ❌ [failing-test-name] - [why it's failing] ### Blockers [List specific blockers OR write "None"] ### Next 3 1. [The immediate next action - be specific] 2. [Then do this] 3. [After that] --- Details → STATUS.md ``` **Feature Overview Guidelines**: - **Slower-changing**: Only update when feature scope/understanding evolves - **50,000-foot view**: High-level context, not implementation details - **Concise**: Each section should be bullets or short sentences - **Backward compatible**: Existing sessions without overview still work - **Created on first snapshot**: Inferred from conversation or prompted from user - **Shared across instances**: All instances working on same feature see same overview ### STATUS.md - Terse Log with Discussion Capture **Purpose**: Chronological breadcrumbs with context | **Size**: No limit, but keep entries SHORT | **Update**: After meaningful steps ```markdown # Status Log [Append-only log - oldest to newest] --- ## [instance:session] YYYY-MM-DD HH:MM - [What we did] **User Request**: [Summarized intent of user's request] **Discussion**: [Key decisions, alternatives considered, trade-offs - omit if obvious] **Outcomes**: ✅/❌ [Outcome] **Next**: [Action] --- [Keep entries SHORT - this is breadcrumbs, not a diary] [Discussion field captures "why" for important decisions] ``` **Good example with discussion:** ``` ## [5d72:888c] 2025-01-12 14:35 - Login page **User Request**: Add certificate and credential authentication **Discussion**: Chose dual auth over single method for flexibility **Outcomes**: ✅ Cert & cred auth working ❌ Cookies broken in tests **Next**: Fix playwright config ``` **Good example without discussion (routine work):** ``` ## [5d72:888c] 2025-01-12 15:10 - Fix tests **User Request**: Fix broken cookie tests **Outcomes**: ✅ Playwright config updated ✅ All tests passing **Next**: Deploy to staging ``` ### LESSONS.md - Bullet Points **Purpose**: Extract patterns that worked/didn't | **Update**: After completing features | **Format**: Bullets, not essays ```markdown # Lessons Learned [Organized by category, not chronologically] --- ## [Feature/Category] ### Pattern: [Name] - Context: [Why we needed this] - Solution: [What worked] → [relative/path/to/file:line] - Gotcha: [What tripped us up] - Use when: [Future scenarios] --- [KEEP IT BULLETS - No essays. Only write what you'll reference again.] ``` **Rule**: If you won't reference it again, don't write it. --- ## Workflow ### Session Start (Claude): 1. Read CURRENT.md (< 1 min) 2. Say: "Resuming: [Right Now]. Next: [Next 3 #1]" 3. Mention blockers if any 4. Start work ### During Work (Claude): 1. Work on task 2. Update CURRENT.md after milestones 3. Append to STATUS.md (terse!) 4. User can walk away anytime ### Context Switch (Rabbit Hole): 1. Move current work to "Paused" 2. Update "Right Now" with new focus 3. Work on new thing 4. Resume later from CURRENT.md ### Feature Complete: 1. Mark in CURRENT.md 2. Final STATUS.md entry 3. Extract bullets to LESSONS.md 4. Update "Next 3"