---
name: handoff-doc
description: Generate comprehensive handoff documentation when transitioning work to another agent or developer. Documents current state, decisions, blockers, and next steps for seamless context transfer.
---

# Handoff Document Generator

Generate a structured handoff document when transitioning work. Run this before pausing, switching context, or transferring to another agent.

## When to Use

- Pausing work mid-task and resuming later
- Transferring to another agent or developer
- Switching branches or contexts
- End of session / work shift handover
- Project status checkpoint

## Process

```
1. GATHER: Collect all context about current work
2. STRUCTURE: Follow the handoff template
3. WRITE: Generate handoff document
4. VERIFY: Check for completeness
```

## Information to Gather

```
CURRENT STATE:
- What was I working on? (task, branch, files)
- What is complete? (commit/task IDs)
- What is in progress? (partial work, WIP)
- What is blocked? (dependencies, decisions pending)

DECISIONS:
- Key design/architecture decisions made
- Why those decisions (rationale, tradeoffs)
- Alternatives considered and rejected

CONTEXT:
- Relevant files and their purposes
- Key functions/classes modified
- External references (docs, issues, PRs)
- Environment/setup details

NEXT STEPS:
- What to do next (ordered priority)
- What to avoid (known pitfalls)
- Recommended approach
- Open questions needing resolution

BLOCKERS:
- External dependencies waiting on
- Decisions pending from stakeholders
- Infrastructure/CI issues
- Knowledge gaps
```

## Handoff Template

Write the output to `HANDOFF.md` in the workspace root (or `handoffs/HANDOFF-{YYYY-MM-DD}.md` for multiple):

```markdown
# Handoff: {YYYY-MM-DD HH:MM}

## Summary
{One paragraph: what was the goal, what state is it in}

## Current State
- **Complete:** {list of finished items}
- **In Progress:** {list of WIP items}
- **Blocked:** {list of blockers with reasons}

## Key Decisions
| Decision | Rationale | Alternative |
|----------|-----------|-------------|
| {decision} | {why} | {what was rejected} |

## Files Touched
| File | Purpose | Status |
|------|---------|--------|
| {path} | {what changed} | {modified/created/deleted} |

## Next Steps (Priority Order)
1. {high priority} — {detail}
2. {medium priority} — {detail}
3. {low priority} — {detail}

## Open Questions
- {question 1} — needs input from {who}
- {question 2} — needs investigation

## Known Pitfalls
- {gotcha 1}
- {gotcha 2}

## Branch Info
- **Branch:** `{current-branch}`
- **Latest Commit:** `{commit-hash}` — "{commit-message}"
- **Base Branch:** `{base-branch}`
```

## Quick Handoff (for lightweight context switches)

When time is limited, generate a compact version:

```
## Handoff Summary ({YYYY-MM-DD})
Goal: {one line}
Status: {done/in-progress/blocked} — {1 sentence}
Key decision: {1 sentence}
Next: {1-2 sentences}
Branch: {branch}
Files: {key files only}
```

## Examples

### Full handoff (complex feature, multi-session)
```
Follow the full template above. Focus on decisions and rationale — 
the next agent needs to know WHY, not just WHAT.
```

### Quick handoff (simple bugfix, short interruption)
```
Use the compact summary. Omit template sections that are empty.
```

## Verification Checklist

Before finalizing the handoff, verify:

- [ ] Summary answers: "What is this about?"
- [ ] Current state accurately reflects reality
- [ ] Key decisions include rationale (not just what)
- [ ] Next steps are actionable (not vague)
- [ ] Blocker dependencies are identified
- [ ] Branch/commit info is correct
- [ ] No sensitive credentials or secrets exposed
- [ ] Handoff document is saved to a durable location