168 lines
4.9 KiB
Markdown
168 lines
4.9 KiB
Markdown
---
|
|
title: "Session Handoff Template"
|
|
description: "Structured context handoff template triggered at 85% context usage to preserve intent"
|
|
tags: [template, memory, workflows]
|
|
---
|
|
|
|
# Session Handoff Template
|
|
|
|
**Inspired by**: [Robin Lorenz's Context Engineering approach](https://www.linkedin.com/posts/robin-lorenz-54055412a_claudecode-contextengineering-aiengineering-activity-7425136701515251713) (Feb 2026)
|
|
|
|
**Purpose**: Structured handoff to preserve intent when approaching context limits. Triggers at **85% context usage** to prevent auto-compact quality degradation.
|
|
|
|
---
|
|
|
|
## Session Metadata
|
|
|
|
**Date**: YYYY-MM-DD
|
|
**Project**: [Project Name]
|
|
**Context Trigger**: X% (recommended: 85%)
|
|
**Session ID**: [Optional - for reference]
|
|
|
|
---
|
|
|
|
## ✅ Completed Work
|
|
|
|
List all work finished in this session with commit references:
|
|
|
|
- **[Task 1]**: Description of what was accomplished
|
|
- Commit: `abc123`
|
|
- Files: `src/feature.ts`, `tests/feature.test.ts`
|
|
|
|
- **[Task 2]**: Another completed item
|
|
- Commit: `def456`
|
|
- Files: `config/settings.json`
|
|
|
|
**Git status check**:
|
|
```bash
|
|
# Run before handoff to capture state
|
|
git status
|
|
git log -5 --oneline
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 Pending Tasks
|
|
|
|
Tasks started but not completed, with percentage and blockers:
|
|
|
|
- **[Task 3]**: Brief description
|
|
- **Progress**: 80% complete
|
|
- **Blocker**: Waiting for API key / Need to clarify requirements
|
|
- **Next action**: [Specific next step]
|
|
- **Files touched**: `src/pending-feature.ts`
|
|
|
|
- **[Task 4]**: Another pending item
|
|
- **Progress**: Research phase (20%)
|
|
- **Blocker**: Need architectural decision on X
|
|
- **Next action**: Review options A vs B
|
|
|
|
---
|
|
|
|
## 🚧 Blockers & Issues
|
|
|
|
Critical blockers that need resolution before proceeding:
|
|
|
|
1. **[Blocker 1]**: Detailed description of what's blocking progress
|
|
- **Impact**: What this blocks
|
|
- **Workaround**: Temporary solution if any
|
|
- **Resolution path**: How to unblock
|
|
|
|
2. **[Issue 1]**: Technical debt or bug discovered
|
|
- **Severity**: High/Medium/Low
|
|
- **Workaround**: Current mitigation
|
|
|
|
---
|
|
|
|
## ➡️ Next Steps
|
|
|
|
Prioritized action items for the next session:
|
|
|
|
1. **[High Priority]**: First action to take when resuming
|
|
2. **[High Priority]**: Second critical action
|
|
3. **[Medium]**: Follow-up task after priorities
|
|
4. **[Low]**: Nice-to-have or exploratory task
|
|
|
|
**Immediate start**: When resuming, begin with [specific file/task].
|
|
|
|
---
|
|
|
|
## 📌 Essential Context
|
|
|
|
Critical information that MUST be preserved (decisions, patterns, constraints):
|
|
|
|
### Architectural Decisions
|
|
- **Decision 1**: We chose approach X over Y because [rationale]
|
|
- **Pattern established**: All new features must follow [pattern]
|
|
|
|
### Technical Constraints
|
|
- **Constraint 1**: Can't use library X due to [reason]
|
|
- **Constraint 2**: Must maintain compatibility with [system]
|
|
|
|
### Domain Knowledge
|
|
- **Business rule**: Important rule discovered during implementation
|
|
- **Edge case**: [Unusual scenario] requires [special handling]
|
|
|
|
### Dependencies
|
|
- **External**: Waiting on [team/service] for [dependency]
|
|
- **Internal**: Feature X depends on completion of Y
|
|
|
|
---
|
|
|
|
## 🔄 Resume Instructions
|
|
|
|
**For next session**:
|
|
|
|
```bash
|
|
# Load this handoff into new session
|
|
cat claudedocs/handoffs/handoff-YYYY-MM-DD.md | claude -p
|
|
|
|
# Or reference manually
|
|
claude
|
|
# Then: "Continue from handoff document in claudedocs/handoffs/handoff-YYYY-MM-DD.md"
|
|
```
|
|
|
|
**Context check**:
|
|
```bash
|
|
# After resuming, verify context state
|
|
/status
|
|
```
|
|
|
|
**If context still high (>70%)**: Consider breaking into smaller focused sessions.
|
|
|
|
---
|
|
|
|
## 📊 Session Stats (Optional)
|
|
|
|
- **Turns**: ~X (approaching degradation threshold at 15-25 turns)
|
|
- **Context usage**: X% (triggered handoff at 85%)
|
|
- **Duration**: X hours
|
|
- **Commits**: X commits pushed
|
|
|
|
---
|
|
|
|
## 💡 Why This Template?
|
|
|
|
**Research-backed rationale**:
|
|
|
|
- **Auto-compact degrades quality**: LLM performance drops 50-70% on complex tasks at high context ([Context Rot Research](https://research.trychroma.com/context-rot))
|
|
- **Manual handoff preserves intent**: Structured documentation captures "what matters" vs "degraded version of everything"
|
|
- **85% threshold prevents auto-compact**: Auto-compact triggers at ~75% (VS Code) or ~95% (CLI), so 85% provides safety margin
|
|
- **Logical breakpoint > automatic compression**: Community consensus favors manual `/compact` at breakpoints
|
|
|
|
**Key principle**: "A handoff gives you a clean version of what matters" — Robin Lorenz
|
|
|
|
---
|
|
|
|
## 📚 Related Resources
|
|
|
|
- [Session Handoffs (Ultimate Guide)](../../guide/ultimate-guide.md#session-handoffs)
|
|
- [Auto-Compaction Research (Architecture)](../../guide/architecture.md#auto-compaction)
|
|
- [Fresh Context Pattern (Ultimate Guide)](../../guide/ultimate-guide.md#fresh-context-pattern)
|
|
- [Lorenz's Original Post](https://www.linkedin.com/posts/robin-lorenz-54055412a_claudecode-contextengineering-aiengineering-activity-7425136701515251713)
|
|
|
|
---
|
|
|
|
**Template Version**: 1.0
|
|
**Last Updated**: 2026-02-08
|
|
**Maintenance**: Update as research evolves
|