create-handoff

name	create-handoff
description	Create a handoff document to preserve context before clearing. Use when user says 'create handoff', context is low, or before '/clear'.
allowed-tools	Read, Glob, Grep, Write, Edit

Create Handoff

You are an expert at capturing context for seamless session continuation. Handoffs are structured documents that allow a fresh session to resume work without losing progress.

When To Use

• User says "create handoff" or "/create_handoff"
• Context/remaining tokens below 10%
• Before using /clear
• At natural breakpoints in long implementations
• When switching tasks temporarily
• End of work session
• Pre-implementation: Before starting implement-plan (if context > 30%)

Modes

Standard Mode (Default)

Full handoff with all context preserved. Use at end of session or before /clear.

Pre-Implementation Mode

Lightweight handoff before starting a plan. Triggered when:

• User is about to run implement-plan
• Context is already > 30%

Pre-implementation handoff captures:

• Current conversation summary (2-3 sentences)
• Any decisions already made
• Reference to the plan file

Then suggests: "Run /compact then implement plan @plan-file"

Why Handoffs > Auto-Compact

• Explicit control: You decide what's preserved
• Structured format: Easy to parse and resume
• Versioned: Handoffs are committed to repo
• Shareable: Another agent or human can continue
• No context loss: Everything important is captured

Inputs

• Current session context
• Active plan file (if any)
• Current state of implementation
• Any blockers or open questions

Outputs

• Handoff file at: thoughts/shared/handoffs/YYYY-MM-DD-[ticket_id]-description.md
• Updated TODO.md with current state
• Clear next steps documented

Handoff Document Structure

# Handoff: [Task/Feature Name]

**Created**: YYYY-MM-DD HH:MM
**Session**: [Session ID if available]
**Ticket**: [ID if applicable]

## Quick Summary
[2-3 sentences on what was being done]

## Current State

### What's Done
- [x] Completed item 1 (commit: abc123)
- [x] Completed item 2 (commit: def456)

### In Progress
- [ ] Current task being worked on
  - What's done: [specifics]
  - What remains: [specifics]

### Not Started
- [ ] Remaining task 1
- [ ] Remaining task 2

## Active Files

Files currently being worked on:
- `src/auth/login.ts` - Implementing login logic, line 45-80 needs completion
- `tests/auth.test.ts` - 3 tests passing, 2 pending

## Context to Preserve

### Key Decisions Made
1. Decision: [what] | Rationale: [why]
2. Decision: [what] | Rationale: [why]

### Important Discoveries
- [Thing learned during implementation]
- [Gotcha or edge case found]

### Technical Notes
- [Architecture note]
- [Performance consideration]
- [Security note]

## Blockers / Open Questions

| # | Question/Blocker | Status | Notes |
|---|-----------------|--------|-------|
| 1 | [Question] | Waiting on user | Asked at HH:MM |
| 2 | [Blocker] | Investigating | Possible solutions: A, B |

## Beads State (Persistent Tasks)

If project uses beads (.beads/ exists):

### In Progress
[Output of `bd list --status in_progress --json`]

### Ready Next
[Output of `bd ready --json`]


[Tasks with open dependencies]

Related Artifacts

• Plan: thoughts/shared/plans/YYYY-MM-DD-description.md
• TODO.md: Updated with current state
• PRD: PRD.md (if exists)
• Beads: .beads/issues.jsonl (if using beads)

Next Steps (Prioritized)

1. Immediate: [What to do first when resuming]
2. Then: [Second priority]
3. After that: [Third priority]

Resume Instructions

To continue this work:

# In Claude Code
/resume_handoff @thoughts/shared/handoffs/YYYY-MM-DD-description.md

Or manually:

1. Read this handoff document
2. Check TODO.md for current state
3. Review plan file if referenced
4. Continue from "Next Steps"

---

Session Statistics

• Started: [timestamp if known]
• Duration: [if known]
• Commits made: [count]
• Context used: ~[%] when handoff created

## Workflow

### Phase 1: Capture Current State

1. **Identify what's done**: List completed tasks with commits
2. **Capture in-progress work**: Where exactly did you stop?
3. **Note remaining work**: What's left on the plan?

### Phase 2: Document Context

4. **Key decisions**: What choices were made and why?
5. **Discoveries**: What was learned during implementation?
6. **Blockers**: Any unresolved issues?

### Phase 3: Prepare for Resume

7. **Prioritize next steps**: What should happen first?
8. **Reference artifacts**: Link to plan, TODO.md, etc.
9. **Write resume instructions**: Make it easy to continue

### Phase 3.5: Capture Beads State (If Using Beads)

If project has `.beads/` directory:

10. **Sync beads**: Run `bd sync` to push all changes
11. **Capture task states**: Document in-progress, ready, and blocked tasks
12. **Include resume commands**: `bd sync && bd ready --json`

### Phase 4: Finalize

10. **Write handoff file**
11. **Update TODO.md** to reflect current state
12. **Commit handoff**: "docs: create handoff for [feature]"

## Handoff Naming Convention

YYYY-MM-DD-[TICKET_ID]-description-handoff.md

Examples:

• 2025-01-15-AUTH-001-user-auth-handoff.md
• 2025-01-15-no-ticket-dark-mode-handoff.md
• 2025-01-15-session-2-handoff.md

## Best Practices

- **Create early**: Don't wait until context is exhausted
- **Be specific**: "line 45 of login.ts" not "somewhere in login"
- **Include reasoning**: Future you needs the "why"
- **Test resume**: Verify handoff has enough info to continue
- **Commit immediately**: Don't lose the handoff to a crash

## Integration with Plan Workflow

/create_plan idea -> answer questions -> plan created: thoughts/shared/plans/...

/clear

/implement_plan @thoughts/shared/plans/... -> implement steps -> context getting low (5-10%)

/create_handoff -> handoff created: thoughts/shared/handoffs/...

/clear

/resume_handoff @thoughts/shared/handoffs/... -> continue implementation -> repeat until done

## Keywords

create handoff, handoff, save context, preserve context, before clear, session end, context low, take a break, pause work