Handoff Protocols

Handoff Protocols

You are executing a work handoff between team members or agents.

Handoff Types

| Type | When | Key Characteristics |

|------|------|---------------------|

| Planned | End of shift, vacation, role change | Time to prepare docs; opportunity for sync meeting; gradual transition possible |

| Unplanned | Illness, emergency, priority change | Limited prep time; rely on existing docs; may need to reconstruct context |

| Partial | Transfer one piece while retaining other work | Requires clear boundary definition; shared ownership and integration points |

Handoff Document

Essential Sections

# Handoff: [Task/Project Name]

## Quick Summary
[One paragraph: What is this and current state]

## Current Status
- [ ] Phase: [Design/Implementation/Testing/etc]
- [ ] Progress: [X% complete / Y of Z tasks done]
- [ ] Blockers: [Current blockers, if any]
- [ ] Next Action: [Very next thing to do]

## Context

### What We're Building
[Brief description of the goal/feature]

### Why
[Business/technical justification]

### Key Decisions Made
| Decision | Options Considered | Choice | Rationale |
|----------|-------------------|--------|-----------|
| [D1] | A, B, C | B | [Why B was chosen] |

### Open Questions
- [Question 1]
- [Question 2]

## Technical Details

### Architecture/Design
[Relevant diagrams or links]

### Key Files
- `path/to/file1.ts` - [Purpose]
- `path/to/file2.ts` - [Purpose]

### Dependencies
- [Dependency 1]: [How it's used]
- [Dependency 2]: [How it's used]

## Current State of Code

### What's Complete
- [x] [Completed item 1]
- [x] [Completed item 2]

### In Progress
- [ ] [In progress item] - [Current state]

### Not Started
- [ ] [Pending item 1]
- [ ] [Pending item 2]

## Known Issues

### Active Issues
- [Issue 1]: [Description and current understanding]

### Workarounds in Place
- [Workaround 1]: [Why it exists, how to remove it]

## How to Continue

### Immediate Next Steps
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Things to Watch Out For
- [Gotcha 1]
- [Gotcha 2]

### Who to Contact
- [Name/Team] for [Topic]
- [Name/Team] for [Topic]

## Resources
- [Link to design doc]
- [Link to requirements]
- [Link to related PRs]

Handoff Meeting Checklist

If doing a live handoff:

Before Meeting:

• [ ] Prepare handoff document
• [ ] Ensure code is in clean state
• [ ] List questions you anticipate

During Meeting:

• Walk through handoff document
• Show current state of code
• Demo any working functionality
• Explain key decisions and trade-offs
• Highlight risks and unknowns
• Answer questions
• Verify recipient understands

After Meeting:

• [ ] Share access to all resources
• [ ] Offer availability for follow-up questions
• [ ] Confirm handoff complete

Code State Preparation

Before handing off, ensure:

# Clean working directory
git status  # Should be clean

# Latest changes committed
git log -1  # Recent meaningful commit

# Branch is up to date
git pull origin main

# Tests pass
npm test    # All green

# Build works
npm run build  # No errors

Leave the code in a state where:

• It compiles/runs
• Tests pass
• No work-in-progress changes uncommitted
• Clear commit messages explain recent changes

Communication Templates

Async Handoff Message

Hi [Name],

I'm handing off [Task/Project] to you. Here's what you need to know:

**Status:** [Current state in one sentence]

**What I've Done:**
- [Accomplishment 1]
- [Accomplishment 2]

**Next Steps:**
1. [Immediate next action]
2. [Following action]

**Watch Out For:**
- [Important gotcha]

**Resources:**
- Handoff doc: [link]
- Code: [branch name]
- Related PR: [link]

Let me know if you have questions!

Requesting Additional Context

Hi [Name],

I'm picking up [Task] from your handoff. A few clarifications:

1. [Specific question 1]
2. [Specific question 2]

Also, I noticed [observation]. Was that intentional?

Thanks!

Handoff Anti-Patterns

Avoid: brain dumps of unstructured info, disappearing after handoff, omitting critical context, and handing off code in a broken state.

Receiving a Handoff

When you receive work:

• Read documentation before asking questions
• Acknowledge receipt to confirm handoff
• Identify gaps in your understanding
• Ask focused questions about specific unclear points
• Verify you can build/run the current state
• Document any additional context you discover

Handoff Quality Checklist

For the giver:

• [ ] Documentation is complete and current
• [ ] Code is in clean, working state
• [ ] All access/permissions transferred
• [ ] Key contacts introduced
• [ ] Questions answered or noted
• [ ] Availability for follow-up communicated

For the receiver:

• [ ] Documentation reviewed
• [ ] Can build and run the code
• [ ] Understand current state
• [ ] Know next steps
• [ ] Know who to contact
• [ ] No blocking questions

Integration with Other Skills

• structured-review: Get review before handoff if work is complete
• parallel-investigation: Handoff individual threads
• planning/task-decomposition: Reference task breakdown in handoff