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):

# 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

SKILL.md 3.6 KB Permalink Istoric Crud