handoff

Handoff — Session Continuity

You manage session continuity by saving and restoring structured task state across conversations.

ultrathink

Two Modes

This skill operates in one of two modes based on context:

Mode 1: SAVE (default)

Trigger: user says /handoff, "save progress", "let's pause here", or the session is ending after complex work.

Mode 2: RESUME

Trigger: user says /handoff resume, "pick up where I left off", "check handoffs", "what was I working on", or starts a session in a project that has recent handoff files.

---

Mode 1: SAVE — Capture Session State

Step 1: Gather Context

Scan the current conversation to extract:

1. Objective — What were we trying to accomplish? State the goal clearly.
2. Progress — What's done? List completed work with specific file paths and line numbers.
3. Current state — Where exactly did we stop? What was the last thing done or being worked on?
4. Files modified — Every file touched in this session, with a brief note on what changed.
5. Pending work — What remains? List as checkboxes.
6. Key decisions — Decisions made during the session with their rationale. These are the easiest things to lose.
7. Blockers / Open questions — Anything unresolved that the next session needs to address.
8. How to resume — Concrete instructions for picking up: which file to open, which test to run, what to do next.

Also check:

• git status and git diff --stat for uncommitted changes
• git log --oneline -5 for recent commits made in this session
• Any running background tasks or pending agent results

Step 2: Determine Handoff Location

Resolve the project memory directory:

1. Determine the current working directory
2. Map it to the Claude Code project memory path: ~/.claude/projects/<encoded-path>/memory/
3. Create handoffs/ subdirectory if it doesn't exist
4. File name: handoffs/YYYY-MM-DD-<topic-slug>.md

If the topic is unclear, derive it from the objective (e.g., "auth-middleware-refactor", "thesis-chapter-5-revision").

Step 3: Write the Handoff File

Write the handoff file with this exact structure:

---
date: YYYY-MM-DD
topic: <topic>
project: <absolute project path>
status: active
---
# Handoff: <Topic>

## Objective
<Clear statement of what we were trying to accomplish>

## Progress
- [x] Completed item 1 (file: path/to/file.ts, lines 10-50)
- [x] Completed item 2

## Current State
<Exact point of interruption — what was the last thing done>

## Uncommitted Changes
<Output of git status / git diff --stat, or "None — all changes committed">

## Files Modified
- `path/to/file1.ts` — Description of changes
- `path/to/file2.ts` — Description of changes

## Pending Work
- [ ] Remaining task 1
- [ ] Remaining task 2
- [ ] Remaining task 3

## Key Decisions
- Decision 1 — Rationale: why we chose this approach
- Decision 2 — Rationale: why we chose this approach

## Blockers / Open Questions
- Question or blocker that needs resolution

## How to Resume
1. Open <file> and look at <location>
2. Run <command> to verify current state
3. Next step: <specific action to take>

Step 4: Update Memory Indexes

1. Project-local MEMORY.md — Add a one-line entry: - [Handoff: <topic>](handoffs/YYYY-MM-DD-<slug>.md) — <one-line summary of state>

2. Daily log — Append to memory/daily/YYYY-MM-DD.md: - HH:MM — Handoff saved: <topic>. Status: <brief state>.

3. Mark previous handoffs as superseded — If there's an older handoff for the same topic, update its status frontmatter from active to superseded.

Step 5: Confirm to User

Show a brief summary:

• Handoff file location
• Objective captured
• Number of pending items
• How to resume next time ("Start a new session and say 'pick up where I left off' or '/handoff resume'")

---

Mode 2: RESUME — Restore Session State

Step 1: Find Handoff Files

1. Determine the current project memory directory
2. Look for handoffs/ subdirectory
3. List all handoff files, sorted by date (newest first)
4. Filter to status: active only (ignore superseded)

If no handoffs exist, tell the user and offer to check other projects:

• Read MEMORY.md indexes from ~/.claude/projects/*/memory/MEMORY.md
• Look for handoff entries across all projects
• Present any found, noting which project they belong to

Step 2: Present Handoff(s)

If one active handoff: read and present it directly. If multiple active handoffs: show a brief list and ask which to resume.

Present the handoff as a briefing:

## Resuming: <Topic>
**Last session:** <date>
**Objective:** <objective>
**Where we left off:** <current state>
**Pending work:** <N items remaining>

Step 3: Verify Current State

Before diving in, verify the handoff is still accurate:

1. Check if the files mentioned still exist and match expectations
2. Run git status to see if there are changes since the handoff
3. Check git log --oneline -5 for commits since the handoff date
4. If state has changed (someone else worked on it, or the user made manual changes), note the differences

Step 4: Reconstruct Context

Read the key files mentioned in the handoff to rebuild working context:

• Open files listed in "Files Modified"
• Check the specific lines/locations mentioned in "How to Resume"
• Load any relevant daily logs since the handoff date

Present a "ready to go" summary:

## Ready to Resume
- State verified: <matches handoff / has diverged>
- Next step: <from "How to Resume">
- Pending: <checkbox list from handoff>

Ask the user to confirm before proceeding with the pending work.

---

Edge Cases

• No complex work to hand off: If the session was simple Q&A with no task state, say so. Don't create an empty handoff.
• Multiple topics in one session: Create separate handoff files for each distinct topic.
• Handoff during multi-agent work: Note which agents were running and their last known state.
• Stale handoffs: If a handoff is older than 2 weeks and its objective seems completed (based on git history), suggest archiving it.

User's Input

$ARGUMENTS