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 scr