Session Handoff

# Session Handoff Skill ## Overview The Session Handoff skill creates comprehensive handoff documents that enable fresh AI agents to seamlessly continue work with zero ambiguity. It solves the long-running agent context exhaustion problem by preserving complete context, decisions, and state across sessions. ## Purpose When working on complex, multi-session projects with AI agents, context gets lost between sessions. This skill provides a structured approach to: - **Preserve context** - Capture all critical information before context window fills - **Enable continuity** - Allow new agents to pick up exactly where you left off - **Document decisions** - Record architectural choices and their rationale - **Track progress** - Maintain clear status of completed and pending work - **Chain sessions** - Link related handoffs for long-running projects ## When to Use ### User-Triggered - User says "save state", "create handoff", "I need to pause" - User requests "load handoff", "resume from", "continue where we left off" - User mentions "context is getting full" or "save this for later" ### Agent-Triggered (Proactive) - Context window approaching capacity (>80% full) - Major task milestone completed - Work session ending with significant progress - After substantial work (5+ file edits, complex debugging, architecture decisions) - Before switching to a different task ### Resumption Scenarios - Starting a new session on an existing project - Different agent needs to continue the work - Need to recall decisions made in previous sessions - Picking up after a long break ## How It Works The skill operates in two primary modes: ### CREATE Mode Generates a comprehensive handoff document capturing current state: 1. **Generate Scaffold** - Smart script pre-fills metadata (timestamp, git status, modified files) 2. **Complete Document** - Fill in critical sections (state, context, decisions, next steps) 3. **Validate** - Automated checks for completeness, quality, and security 4. **Confirm** - Present location and summary to user ### RESUME Mode Loads and validates existing handoff documents: 1. **Find Handoffs** - List available handoffs in project 2. **Check Staleness** - Assess if context is still current 3. **Load Document** - Read handoff (and chain if linked) 4. **Verify Context** - Validate assumptions and environment 5. **Begin Work** - Start from "Immediate Next Steps" ## Key Features ### Smart Scaffolding The `create_handoff.py` script automatically captures: - Timestamp and project path - Current git branch and recent commits - Modified and unstaged files - Handoff chain links (if continuing from previous) ### Validation & Quality Assurance The `validate_handoff.py` script checks: - No incomplete `[TODO: ...]` placeholders - All required sections populated - No potential secrets (API keys, passwords, tokens) - Referenced files exist - Quality score (0-100) ### Staleness Detection The `check_staleness.py` script assesses: - Time elapsed since handoff creation - Git commits made since handoff - Files changed since handoff - Branch divergence - Missing referenced files ### Handoff Chaining For long-running projects, chain handoffs together: ``` handoff-1.md (initial work) ↓ handoff-2.md --continues-from handoff-1.md ↓ handoff-3.md --continues-from handoff-2.md ``` Each handoff links to its predecessor, providing context breadcrumbs for new agents. ## Usage Examples ### Creating a Handoff **Basic handoff creation:** ```bash python scripts/create_handoff.py implementing-user-auth ``` **Continuation handoff (linked to previous):** ```bash python scripts/create_handoff.py "auth-part-2" --continues-from 2024-01-15-auth.md ``` **Validate before finalizing:** ```bash python scripts/validate_handoff.py .claude/handoffs/2024-01-15-143022-implementing-auth.md ``` ### Resuming from a Handoff **List available handoffs:** ```bash python scripts/list_handoffs.py ``` **Check if handoff is current:** ```bash python scripts/check_staleness.py .claude/handoffs/2024-01-15-143022-implementing-auth.md ``` **Load and continue work:** 1. Read the handoff document completely 2. Verify context using resume checklist 3. Start with first item in "Immediate Next Steps" ## Handoff Document Structure A complete handoff includes: 1. **Metadata** - Timestamp, project path, git branch, commits 2. **Current State Summary** - What's happening right now 3. **Important Context** - Critical information for next agent 4. **Decisions Made** - Architectural choices with rationale 5. **Immediate Next Steps** - Clear, actionable first steps 6. **Pending Work** - Remaining tasks and priorities 7. **Critical Files** - Important locations and their purpose 8. **Key Patterns Discovered** - Conventions and approaches 9. **Potential Gotchas** - Known issues and workarounds 10. **Handoff Chain** - Links to previous/next handoffs See [references/handoff-template.md](references/handoff-template.md) for the complete template. ## Storage Location Handoffs are stored in: `.claude/handoffs/` Naming convention: `YYYY-MM-DD-HHMMSS-[slug].md` Example: `2024-01-15-143022-implementing-auth.md` ## Scripts Reference | Script | Purpose | Usage | |--------|---------|-------| | `create_handoff.py` | Generate new handoff with smart scaffolding | `python scripts/create_handoff.py [slug] [--continues-from ]` | | `list_handoffs.py` | List available handoffs in a project | `python scripts/list_handoffs.py [path]` | | `validate_handoff.py` | Check completeness, quality, and security | `python scripts/validate_handoff.py ` | | `check_staleness.py` | Assess if handoff context is still current | `python scripts/check_staleness.py ` | ## Quality Standards **Do not finalize a handoff if:** - Validation score is below 70 - Secrets are detected - `[TODO: ...]` placeholders remain - Required sections are empty **Best practices:** - Write clear, specific next steps (not vague goals) - Document the "why" behind decisions, not just the "what" - Include code snippets for critical patterns - Reference specific file paths and line numbers - Update handoffs as work progresses ## References - [handoff-template.md](references/handoff-template.md) - Complete template structure with guidance - [resume-checklist.md](references/resume-checklist.md) - Verification checklist for resuming agents - [evals/model-expectations.md](evals/model-expectations.md) - Model behavior expectations - [evals/test-scenarios.md](evals/test-scenarios.md) - Test cases for handoff creation and resumption ## Benefits - **Zero ambiguity** - New agents know exactly what to do - **Context preservation** - No loss of critical information - **Decision history** - Understand why choices were made - **Reduced onboarding** - Faster agent startup on existing work - **Quality assurance** - Automated validation prevents incomplete handoffs - **Security** - Secret detection prevents credential leaks - **Long-term memory** - Handoff chains maintain project history