Session Handoff

Objective

Save and transfer the context of a work session to enable efficient resumption in a later session or by another agent.

When to use

• End of a work session (save the state)
• Task too complex for a single session
• Handoff between developers/agents
• Documentation of work in progress

Handoff format

Context file: .claude/handoff.md

# Session Handoff

**Date:** [YYYY-MM-DD HH:MM]
**Session:** [ID or description]
**Author:** [Human or agent]

## Project context

**Project:** [Name]
**Branch:** [Branch name]
**Current commit:** [Hash]

## Work state

### Done
- [x] [Task 1] - [Detail]
- [x] [Task 2] - [Detail]

### In progress
- [ ] [Task 3] - [Current state, where it stands]
  - Modified files: [list]
  - Next step: [description]
  - Possible blocker: [description]

### To do
- [ ] [Task 4] - [Description]
- [ ] [Task 5] - [Description]

## Decisions made

| Decision | Reason | Rejected alternative |
|----------|--------|---------------------|
| [Choice 1] | [Why] | [Other option] |
| [Choice 2] | [Why] | [Other option] |

## Key files

| File | Role | State |
|---------|------|------|
| `src/xxx.ts` | [Description] | Modified / Created / To modify |
| `tests/xxx.test.ts` | [Description] | Modified / Created / To create |

## Patterns and conventions discovered

- [Pattern 1 from the codebase]
- [Naming convention]
- [Specific architecture]

## Problems encountered

| Problem | Solution/Workaround | Resolved? |
|----------|---------------------|----------|
| [Problem 1] | [Solution] | Yes/No |
| [Problem 2] | [Workaround] | Partial |

## Notes for the next session

[Specific instructions, pitfalls to avoid, points of attention]

## Useful commands

To resume

git checkout [branch] npm test # Check that everything passes

Next step: [description]

Handoff workflow

Save the context (end of session)

1. SUMMARIZE the work done
2. LIST the modified files (`git diff --stat`)
3. DOCUMENT the decisions made and why
4. IDENTIFY the remaining tasks and their priority
5. NOTE the unresolved problems
6. WRITE the .claude/handoff.md file

Resume the context (start of session)

1. READ the .claude/handoff.md file
2. CHECK the repo state (`git status`, `git log`)
3. RUN the tests to confirm the state
4. IDENTIFY the next task to perform
5. CONTINUE the work

Best practices

• Write the handoff DURING the work, not after
• Be specific about files and lines of code
• Include commands to check the state
• Document the decisions AND the reasons
• Mention the pitfalls and workarounds discovered

Rules

• ALWAYS create a handoff before ending a complex work session
• ALWAYS include the modified files and their state
• ALWAYS document the architectural decisions
• NEVER assume the next session will have the same context