handoff + pickup

handoff.md

name	handoff
description	Generate comprehensive session handoff document
argument-hint	[context notes]
allowed-tools	Read Write Bash Glob

Write a self-contained handoff doc so the next session can pick up cold without re-reading this conversation.

When: end of session, context break, or when state is non-obvious.

Inputs

• $ARGUMENTS — optional inline notes from the user (decisions, gaps, open questions).
• Conversation transcript — primary source for accomplishments, decisions, gaps.
• Git state — branch, last commit, dirty files.

Steps

1. Gather

Run in parallel:

• git rev-parse --abbrev-ref HEAD + git log -1 --oneline + git status --short
• Extract from conversation: files edited, commands run, decisions ("let's…", "go with…"), gaps ("missing", "TODO"), unresolved questions.
• Derive a kebab-case slug for the filename from the session's main thread (e.g. fix-avatar-upload, coach-voice-cues).

2. Write

Path: .claude/handoff/HANDOFF-{YYYY-MM-DD}-{slug}.md

Use the template below. Omit any section with no real content — don't leave empty headings. Keep entries factual and concrete (file paths, commit hashes, command invocations). Cross-reference files with @path/to/file:line so the next session can jump straight in.

# Session Handoff

**Date:** {YYYY-MM-DD HH:MM – HH:MM}
**Branch:** `{branch}`
**Context:** {one-sentence summary of the session's work}

---

## Accomplishments

- {what shipped / was built — include commit hashes if committed}

## Decisions

| Decision          | Rationale | Impact                           |
| ----------------- | --------- | -------------------------------- |
| {what was chosen} | {why}     | {effect on the codebase/product} |

## Gaps & Open Questions

### {Gap or question title}

**Status:** FIXED / PARTIAL / UNKNOWN / DEFERRED / INTENTIONAL
**Notes:** {what's known, what's uncertain, what's the likely culprit}
**Next check:** {concrete diagnostic or test to run}
**Reference:** `@path/to/file:line`

## Environment State

- **Branch:** `{branch}` — {pushed/dirty}
- **Background processes:** {e.g. `pnpm dev` still running}
- **Devices / simulators:** {physical device IDs, sim names, build installed}
- **Test user / data:** {relevant fixtures}

## Reference Files

@path/one @path/two

## Next Actions

| # | Action | Effort |
|---|--------|--------|
| 1 | {concrete, testable step} | {5–30 min} |

---

**Resume:** `/pickup`

3. Confirm

Report in one line: saved path + count of accomplishments / decisions / gaps / next-actions. No ASCII boxes.

Rules

• Do not dump the conversation verbatim — synthesize.
• Every "Next Action" must be concrete enough to execute without context.
• Every "Gap" must name a file and a diagnostic, not just "look into X".
• Skip empty sections entirely rather than writing "N/A".
• Never fabricate commit hashes, file paths, or device IDs — if unsure, omit.

pickup.md

name	pickup
description	Restore context from handoff and continue work
allowed-tools	Read Glob Bash

Rebuild "where did we leave off" at session start and suggest the next action.

Steps

1. Locate

Find the most recent handoff:

• ls -t .claude/handoff/HANDOFF-*.md | head -1
• If none exists, report "No handoff found."

2. Read

Read the handoff file in full. Also run in parallel:

• git rev-parse --abbrev-ref HEAD + git status --short + git log -1 --oneline

Compare the handoff's stated branch/commit against current git state. Flag drift (new commits, different branch, dirty files) — the handoff may be stale.

3. Report

Give the user a tight status block (≤15 lines):

Branch: {current} {(drift from handoff if any)}
Last handoff: {filename} ({date})
Context: {one-line from handoff}

State:
- {1–3 bullets on what's done / in-flight}

Open:
- {1–3 bullets on gaps or next actions}

Suggested next: {highest-priority action from handoff, or "confirm direction"}

Do not paste the whole handoff back — the user wrote it, they know the shape. Synthesize.

4. Archive (after user confirms direction)

Once the user commits to a direction (picks an action, starts editing, or says "go"), move the consumed handoff to .claude/handoff/archive/ so it doesn't pollute future pickups. Create the dir if missing. Do not archive until work has actually begun.

Rules

• If git state has diverged significantly from the handoff, say so explicitly before suggesting next actions.
• Never archive a handoff until the user has acted on it — premature archive loses context on a context-break mid-pickup.