Maintain "just enough" context across work sessions using CURRENT.md, STATUS.md, and LESSONS.md files. Activate when tasks take >15 minutes, touch 3+ files, interruptions likely, or scope uncertain.
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.
Activate this skill when ANY of these are true:
/snapshot or /pickup commandsDefault 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.
✅ Do:
❌ Don't:
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.
Automatic Monitoring: Check token budget in <system-reminder> tags throughout conversation.
When < 10% Remaining (~<20k tokens):
/clear soon to avoid interruption."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):
/clear now recommended to avoid interruption."Why this approach: No waiting for context compaction, seamless continuation, user control, preserves work.
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)
Scenario: Multiple Claude instances working on same feature simultaneously
Solution: Tagged sections in single files using [instance-id:session-id] format
Instance ID (which IDE window):
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):
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])
CURRENT.md (shared Feature Overview + separate sections per instance):
# [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):
# 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):
/snapshot updates or creates its own [instance:session] section/pickup shows all instances for all featuresCRITICAL: Use Relative Paths Only
When writing file paths in session files, ALWAYS use relative paths from the feature's working directory:
frontend/src/routes/+page.svelte, api/main.py, docker-compose.ymlC:\Projects\agent-spike\projects\mentat\api\main.py, projects/mentat/frontend/src/.../home/user/code/app/main.pyRationale:
.session/feature/mentat/ should use api/main.py not projects/mentat/api/main.pyPurpose: 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
# [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:
Purpose: Chronological breadcrumbs with context | Size: No limit, but keep entries SHORT | Update: After meaningful steps
# 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
Purpose: Extract patterns that worked/didn't | Update: After completing features | Format: Bullets, not essays
# 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.
.session/completed/[feature-name]mv .session/feature/[name] .session/completed/[name]/snapshot Command)Purpose: Manual failsafe for capturing state before interruptions, reboots, context switches, or risky work.
When to Snapshot: Before system reboots, meetings/interruptions, context switches, risky refactoring, end of work day, or any time user requests /snapshot
/, \, or special chars. Sanitize if needed, ask user to confirm.mkdir -p ".session/feature/<feature-name>"test -f each filels -lh directory and report sizesFill CURRENT.md with:
Append to STATUS.md:
/pickup Command)Purpose: Resume work from a saved session.
Resuming [feature-name]: [Right Now]
Last done: [Item #1 from Last 5 Done]
[If STATUS.md exists:]
Recent work:
- [Timestamp] [Outcome summary]
- [Timestamp] [Outcome summary]
Next: [Item #1 from Next 3]
[If blockers:]
⚠️ Blockers: [Blockers]
[If LESSONS reminder needed:]
💡 Consider documenting patterns in LESSONS.md
When task meets criteria OR /snapshot//pickup invoked:
Check git tracking policy (MUST do FIRST before creating session files):
Step 1a: Check if .claude/CLAUDE.md exists in project root
test -f .claude/CLAUDE.mdStep 1b: If .claude/CLAUDE.md exists, search for session commit setting
enable-session-commits:\s*true in .claude/CLAUDE.mdStep 1c: Apply policy based on search result
IF "enable-session-commits: true" FOUND:
.gitignore.session/ to gitignoreIF "enable-session-commits: true" NOT FOUND (or .claude/CLAUDE.md doesn't exist):
.gitignore exists: test -f .gitignore.gitignore exists: Read and check for .session/ line. Add if missing under "Session-specific directories" section..gitignore missing: Create with minimum content:# Session-specific directories
.session/
Create structure: .session/feature/[feature-name]/
Initialize files: CURRENT.md, STATUS.md, LESSONS.md (see templates above)
Tell user: "Session context tracking active for [feature-name]"
Update frequently: After milestones, stay terse, monitor token budget
Every 5-10 features, review and ask:
Goal: Continuous improvement toward "just enough"
✅ Resume work in < 2 minutes from cold start ✅ CURRENT.md stays under ~100 lines ✅ STATUS.md entries are terse (< 50 words) ✅ Can walk away anytime without loss ✅ Find "why" in < 3 minutes when needed ✅ Token usage is efficient ✅ Self-evaluation shows we err on "less"
Works alongside:
testing-workflow - Test results in CURRENT.mdgit-workflow - Commit SHAs in STATUS.md if relevantpython-workflow / web-projects - Same context systemThis skill provides working memory. Other skills provide domain knowledge.