tomevault-io 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.