Session Handoff

<!-- AUTO-GENERATED by export-skills.py — DO NOT EDIT -->
---
name: session-handoff
description: Create comprehensive handoff documents for seamless AI agent session transfers. Use when context window approaches capacity, major task milestones are completed, work sessions are ending, or resuming work from a previous session. Solves long-running agent context exhaustion by enabling fresh agents to continue with zero ambiguity.
tags: [session, handoff, context, continuity, agents]
---

# Session Handoff

Create and resume from comprehensive handoff documents for seamless AI agent session transfers. Solves the critical problem of context exhaustion in long-running agent sessions.

## When to Use

- Context window approaching capacity after extensive work
- Major task milestone completed (good checkpoint)
- Work session ending and continuation expected
- Resuming work with "load handoff", "resume from", "continue where we left off"
- After 5+ file edits or complex debugging sessions (proactive suggestion)

## Mode Selection

Determine mode from user intent:

| User Says | Mode |
|---|---|
| "save state", "create handoff", "I need to pause" | **CREATE** |
| "context is getting full", "running out of context" | **CREATE** |
| "load handoff", "resume from", "continue where we left off" | **RESUME** |
| (after 5+ file edits or complex debugging) | **SUGGEST CREATE** |

## CREATE Workflow

### Step 1: Generate Handoff Document

Create the handoff file at `.claude/handoffs/YYYY-MM-DD-HHMMSS-{task-slug}.md`.

### Step 2: Fill Required Sections

```markdown
# Session Handoff: {Task Description}

## Date
{YYYY-MM-DD HH:MM}

## Current State Summary
- What was being worked on
- Current progress (percentage or phase)
- What is working vs. what is not

## Important Context
- Key decisions made and WHY
- Architecture/design choices
- Gotchas discovered
- Environment or config specifics

## Files Modified
- `path/to/file1.py` - What was changed and why
- `path/to/file2.ts` - What was changed and why

## Immediate Next Steps
1. First thing to do (most specific)
2. Second thing to do
3. Third thing to do

## Decisions Made
| Decision | Rationale | Alternatives Considered |
|---|---|---|
| Chose X over Y | Because Z | A, B, C |

## Open Questions
- Unresolved issues needing investigation
- Questions for the user

## Dependencies & Blockers
- External dependencies
- Blocked items with reason

## Commands to Run
```bash
# Commands needed to get back to working state
```
```

### Step 3: Validate Completeness

Check that the handoff document has:
- [ ] Current State Summary is specific (not vague)
- [ ] Next Steps are numbered and actionable
- [ ] All modified files are listed with change descriptions
- [ ] Decisions include rationale
- [ ] No placeholder text remaining

### Step 4: Confirm with User

Present the handoff for review before finalizing.

## RESUME Workflow

### Step 1: Find Handoffs

List available handoffs:
```bash
ls -la .claude/handoffs/*.md 2>/dev/null
```

### Step 2: Check Staleness

| Age | Status | Action |
|---|---|---|
| < 24h | FRESH | Resume directly |
| 24h - 72h | SLIGHTLY STALE | Verify files haven't changed |
| 3d - 7d | STALE | Re-read all listed files, check git log |
| > 7d | VERY STALE | Treat as reference only, re-assess |

### Step 3: Load and Verify

1. Read the handoff document
2. Verify listed files still exist and match expectations
3. Check git log for changes since handoff date
4. If conflicts found, report to user before proceeding

### Step 4: Resume Work

Begin from "Immediate Next Steps" item #1.

### Step 5: Update or Chain

For continued long sessions, create a new handoff that links to the previous one:

```markdown
## Continues From
- `.claude/handoffs/2026-02-27-143022-auth-refactor.md`
```

## Handoff Chaining

For multi-session projects, handoffs form a chain:

```
Session 1 handoff → Session 2 handoff → Session 3 handoff
                     (continues-from)    (continues-from)
```

Each handoff captures its own context while linking to predecessors for full history.

## Storage Convention

```
.claude/handoffs/
  2026-02-28-093015-api-migration.md
  2026-02-28-143022-auth-refactor.md
  2026-02-27-110000-database-schema.md
```

## Anti-Patterns

| Avoid | Why | Instead |
|---|---|---|
| Vague state descriptions | Next agent can't understand progress | Be specific: "3 of 5 endpoints migrated" |
| Missing file list | Agent wastes time re-discovering changes | List every modified file with change summary |
| No decision rationale | Agent re-debates settled decisions | Record WHY, not just WHAT |
| Skipping open questions | Blockers get rediscovered | Document unknowns explicitly |
| Overly long handoffs | Context budget wasted on history | Focus on actionable current state |
| Not checking staleness | Handoff may reference stale state | Always verify before resuming |

## References

- Based on [softaworks/agent-toolkit session-handoff](https://github.com/softaworks/agent-toolkit/tree/main/skills/session-handoff) (MIT License)

<!-- Source: .faos/custom/skills/tools/session-handoff/SKILL.md -->