Handoff Create

Generate a comprehensive session handoff document optimized for Claude Code (AI), not humans. This document must capture everything needed for a fresh session to seamlessly continue work without context loss or repeating mistakes.

Optional argument: If $ARGUMENTS is provided, use it as the session focus/context hint (e.g., /handoff:create clipboard mode implementation).

Instructions

1. Check for existing HANDOFF.md and make a decision:

   • Look for HANDOFF.md in project root
   • If it exists, READ IT FIRST and assess:

   Decision Matrix:

   Condition	Action
   Outdated (different goal, old session, no longer relevant)	Rewrite completely - start fresh
   Overlapping (same project area, related work, useful context)	Merge - preserve relevant issues, failed approaches, decisions; update with current session
   Continuation (exact same task, was interrupted)	Append - add new progress to existing structure

   • If rewriting: still extract any "Failed Approaches" or "Issues & Solutions" that remain relevant
   • If merging: clearly mark what came from previous session vs current session
   • Briefly note your decision in the handoff: > Previous handoff: [rewritten/merged/appended] - [reason]

2. Analyze the current session thoroughly:

   • Review all files created, modified, or deleted
   • Review all commands executed and their outcomes
   • Identify the current todo list state (pending, in_progress, completed items)
   • Identify any issues encountered and how they were resolved
   • Note any failed approaches or dead ends
   • Capture architectural/design decisions made

3. Create HANDOFF.md with the following structure (include sections only if relevant):

# Session Handoff
> Generated: [timestamp]
> Session Focus: [1-line summary]

## MANDATORY FIRST STEPS
- [ ] Read MEMORY.md if it exists (contains persistent project context)
- [ ] Run `git status` to verify current state
- [ ] [Any other critical first steps specific to this project]

## Goal
[What we're trying to accomplish - the high-level objective. Skip if purely exploratory session]

## Todo Status
[Dump the current todo list state exactly as it stands]
- [x] Completed items
- [~] In progress items (mark current focus)
- [ ] Pending items

## Current State
[What is happening RIGHT NOW - where exactly did we stop]
- **Active file:** [file being worked on]
- **Active task:** [specific task in progress]
- **Blocker (if any):** [what's blocking progress]

## Session Work Log

### Files Changed
| File | Action | Purpose |
|------|--------|---------|
| path/to/file | created/modified/deleted | why |

### Infrastructure & Setup
[Any servers started, environment configured, dependencies installed, etc.]
- Commands to restart services: `...`
- Environment variables set: `...`
- Ports in use: `...`

### Design Decisions
[Key architectural or implementation choices made and WHY]
1. Decision: [what] — Rationale: [why]

## Issues & Solutions (CRITICAL)
[Problems encountered and how they were fixed - prevents repeating troubleshooting]

### Issue 1: [Title]
- **Symptom:** [what went wrong]
- **Root cause:** [why it happened]
- **Solution:** [how it was fixed]
- **Time wasted:** [optional - emphasizes importance]

### Gotchas & Warnings
- [Things that look right but aren't]
- [Outdated docs or misleading information encountered]
- [Race conditions, timing issues, etc.]

## Failed Approaches (DO NOT REPEAT)
[Approaches attempted that did not work]
1. **Tried:** [approach] — **Failed because:** [reason]

## Code Context
[Actual code signatures, not descriptions - show don't tell]
```python
# Key function signatures or patterns established
def example_function(param: Type) -> ReturnType:
    ...

Resume Instructions

[Step-by-step what to do next, in order]

1. First action with expected outcome
2. Second action with expected outcome
3. ...

Environment Notes

• Python version / Node version / etc.
• Virtual env location
• Test commands: ...
• Build commands: ...

4. **Save as HANDOFF.md** in project root

5. **Report to user:** Confirm the file path and give a 2-line summary of what was captured.

## Style Guidelines
- Write for AI consumption: dense, structured, no fluff
- Use actual code/commands, not descriptions
- Be specific: file paths, line numbers, exact error messages
- Failed approaches section is MANDATORY if anything was abandoned
- Keep it scannable with clear headers and bullet points