Handoff Template
Use this template structure when creating handoff documents. The smart scaffold script will pre-fill metadata sections; complete the remaining sections based on session context.
Table of Contents
- Session Metadata
- Current State Summary
- Codebase Understanding
- Work Completed
- Pending Work
- Context for Resuming Agent
- Environment State
- Related Resources
- Template Usage Notes
Handoff: [TASK_TITLE]
Session Metadata
- Created: [TIMESTAMP]
- Project: [PROJECT_PATH]
- Branch: [GIT_BRANCH]
- Session duration: [APPROX_DURATION]
Current State Summary
[One paragraph: What was being worked on, current status, and where things left off]
Codebase Understanding
Architecture Overview
[Key architectural insights discovered during this session - how the system is structured, main components, data flow]
Critical Files
| File | Purpose | Relevance |
|---|---|---|
| path/to/file | What this file does | Why it matters for this task |
Key Patterns Discovered
[Important patterns, conventions, or idioms found in this codebase that the next agent should follow]
Work Completed
Tasks Finished
- Task 1 - brief description of what was done
- Task 2 - brief description
Files Modified
| File | Changes | Rationale |
|---|---|---|
| path/to/file | Description of changes | Why this change was made |
Decisions Made
| Decision | Options Considered | Rationale |
|---|---|---|
| Chose X over Y | X, Y, Z | Why X was chosen |
Pending Work
Immediate Next Steps
- [Most critical next action - what to do first]
- [Second priority]
- [Third priority]
Blockers/Open Questions
- Blocker: [description] - Needs: [what's required to unblock]
- Question: [unclear aspect] - Suggested: [potential resolution]
Deferred Items
- Item 1 (deferred because: [reason, e.g., out of scope, needs user input])
Context for Resuming Agent
Important Context
[Critical information the next agent MUST know to continue effectively - this is the most important section for handoff]
Assumptions Made
- Assumption 1: [what was assumed to be true]
- Assumption 2: [another assumption]
Potential Gotchas
- [Things that might trip up a new agent - edge cases, quirks, non-obvious behavior]
Environment State
Tools/Services Used
- [Tool/Service]: [relevant configuration or state]
Active Processes
- [Any background processes, dev servers, watchers that may be running]
Environment Variables
- [Key env vars that matter for this work - DO NOT include secrets/values, just names]
Related Resources
- [Link to relevant documentation]
- [Related file paths]
- [External resources consulted]
Template Usage Notes
When filling this template:
- Be specific and concrete - vague descriptions don't help the next agent
- Include file paths with line numbers where relevant (e.g.,
src/auth.ts:142) - Prioritize the "Important Context" and "Immediate Next Steps" sections
- Don't include sensitive data (API keys, passwords, tokens)
- Focus on WHAT and WHY, not just WHAT - rationale is crucial for handoffs