Create/update detailed work handover notes for seamless continuation
Generates comprehensive handover documentation capturing current project context across three files for seamless continuation.
/plugin marketplace add alvis/.claude/plugin install coding@alvisprefixGenerates comprehensive handover documentation capturing current project & work context across three complementary files: CONTEXT.md (status & decisions), NOTES.md (implementation insights & solutions), and PLAN.md (goals & tasks) for seamless project continuation without requiring prior context
What this command does NOT do:
When to REJECT:
When file path argument points to non-markdown files
When requested to perform git operations instead of documentation
When asked to modify project source code
When the working directory is not a git repository
When user requests code analysis instead of handover documentation
Untracked files: !git ls-files --others --exclude-standard
ultrathink: you'd perform the following steps
Before performing handover documentation, deeply analyze the complete project context:
File naming examples:
CONTEXT.md, NOTES.md, PLAN.mdsprint1-CONTEXT.md, sprint1-NOTES.md, sprint1-PLAN.mdClassify each file into one of three categories with detailed substates:
need-completion: Files with TODO/FIXME comments indicating incomplete implementationneed-fixing: Files with test failures, errors, or HACK/WORKAROUND commentsneed-linting: Files with linting/formatting issues or style violationsneed-refactoring: Files with REFACTOR comments or code quality concernsneed-draft: Untracked files or files with mostly TODOs requiring initial skeletonneed-testing: Files without corresponding test files or lacking test coverageFor each file, gather:
When updating existing handover files, apply intelligent pruning to keep documentation focused and actionable:
Pruning Rules:
Search for and document (with pruning applied):
For CONTEXT.md:
For NOTES.md:
For PLAN.md:
Before documenting any information in the handover files, identify and consult the user on all high-level decisions that require user input. You MUST NOT make architectural, technical, or strategic decisions without user consultation.
Actions:
Identify Decision Points:
Categorize Decisions:
Consult User with AskUserQuestion:
For EACH identified decision:
Present the decision clearly with context
Provide 3-5 viable options with brief pros/cons
ALWAYS include these TWO special options:
Use AskUserQuestion tool with format:
Decision: [Clear statement of what needs to be decided]
Context: [Why this decision matters, from project analysis]
Options:
1. [Option 1] - [Brief rationale and trade-offs]
2. [Option 2] - [Brief rationale and trade-offs]
3. [Option 3] - [Brief rationale and trade-offs]
4. Perform research - Launch deep research on this topic
5. Defer decision - Document as open question in handover
Record user's choice for each decision
Handle user selections appropriately
Process Decision Outcomes:
For finalized decisions:
For "Perform research" selections:
research-[topic-slug].md in working directoryFor "Defer decision" selections:
Handle Multiple Decisions:
Example Decision Consultation:
Decision: Caching Strategy for User Sessions
Context: Analysis shows 3 TODO comments about session management.
System has high read load (from git commit messages mentioning performance).
Options:
1. Redis - Industry standard, persistent, supports clustering (requires Redis setup)
2. Memcached - Simpler, faster for pure caching (loses data on restart)
3. In-memory with Node - No external deps (doesn't scale across instances)
4. Perform research - Launch deep research on caching strategies
5. Defer decision - Document as open question, use simple approach for now
[If user selects option 1: Redis]
β Store in decisions: "Use Redis for session caching - provides persistence and clustering"
β Prepare for CONTEXT.md: "Key Decisions & Patterns" and "Dependencies & Configuration"
β Prepare for PLAN.md: "Set up Redis for session caching"
[If user selects "Perform research"]
β Launch research agent on "session caching strategies for high-load Node.js applications"
β Save results to research-session-caching.md
β Prepare for PLAN.md: "π Review research-session-caching.md and decide on caching strategy"
β Prepare for NOTES.md: Link to research file in "Open Questions"
[If user selects "Defer decision"]
β Prepare for NOTES.md: "Open Questions - Session Caching Strategy: Redis vs Memcached vs in-memory"
β Prepare for PLAN.md: "β οΈ DECISION REQUIRED: Session caching strategy - See NOTES.md"
β Identify blocked tasks: "Implement session persistence - βΈοΈ Blocked by caching decision"
Important Notes:
First, generate current timestamp:
date -u +"%Y-%m-%dT%H:%M:%SZ" to get current ISO 8601 timestampThen, prepare decision-based content from Step 5:
Before generating/updating documents, organize all decision outcomes from Step 5:
Apply Pruning Principles: Before updating or creating files, remember to proactively remove any content that is not useful for future execution phases (see Step 4 pruning rules). This ensures handover documentation remains focused and actionable.
If the files exist:
date commandIf the files don't exist:
date command for all timestamp fieldsCONTEXT.md Structure:
Note: All dates and timestamps in CONTEXT.md must use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
Generate timestamp with: date -u +"%Y-%m-%dT%H:%M:%SZ"
# Work Handover - [Project Name]
**Last Updated**: [Use actual timestamp from `date -u +"%Y-%m-%dT%H:%M:%SZ"`]
**Current Branch**: [branch name]
**Working Directory**: [pwd]
## Background & Context
Why this work is being done - business context, problem being solved, user need.
Sources: README.md, DESIGN.md, commit messages, code comments.
## Goals & Objectives
What this work aims to achieve - specific outcomes and success criteria.
Include: completion targets, test coverage goals, deadlines if mentioned.
## Reference Documents
- Design docs, specifications, architecture docs
- Tickets, issues, PRs with links
- Related documentation or external resources
## Current State
Brief summary of where the work currently stands (2-3 sentences).
## File Status
### π§ In Progress
- `path/to/file.ts` (need-completion) - 3 TODOs remaining: logout, error handling, tests
- `path/to/file.ts` (need-fixing) - 2 failing tests, auth flow error
- `path/to/file.ts` (need-linting) - TypeScript strict mode violations
- `path/to/file.ts` (need-refactoring) - complexity reduction needed, extract utilities
### π Planned
- `path/to/file.ts` (need-draft) - Modal component skeleton needed
- `path/to/file.ts` (need-testing) - Form component needs test coverage
### β
Completed
- 15 files completed (details archived to Historical Notes)
- Recent: Button.tsx, validation.ts, button.test.tsx
## Historical Notes (Archived)
[Older completed items details, commits beyond last 5, verbose descriptions...]
## Recent Changes
### [Date] - [Commit hash]
- Change description from commit message
- Key files affected
## Key Decisions & Patterns
- **Decision**: [what was decided - from Step 5 finalized decisions OR from code/commits]
**Rationale**: [why it was decided - include alternatives considered from Step 5]
**Impact**: [what it affects]
**Alternatives Considered**: [options that were evaluated but not chosen - from Step 5]
## Gotchas & Workarounds
- **Issue**: [problem encountered]
**Workaround**: [how it was handled]
**Location**: [file:line]
## Dependencies & Configuration
- Package/library added: version and purpose
- Config changes: what and why
## Next Steps
1. [Immediate next action with context]
2. [Following action]
3. [Future consideration]
## Context for Continuation
Additional context needed to pick up this work:
- Background information
- Related documentation
- Testing considerations
NOTES.md Structure:
Note: All dates and timestamps in NOTES.md must use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
Generate timestamp with: date -u +"%Y-%m-%dT%H:%M:%SZ"
# Implementation Notes - [Project Name]
**Last Updated**: [Use actual timestamp from `date -u +"%Y-%m-%dT%H:%M:%SZ"`]
**Purpose**: Document issues encountered during implementation that required multiple tool calls to resolve
## Implementation Issues Resolved
### Issue: [Description]
**Problem**: [What went wrong, when encountered]
**Symptoms**: [How it manifested]
**Root Cause**: [Why it happened, if discovered]
**Solution**: [How it was fixed - what multiple steps/tool calls were needed]
**Lessons Learned**: [Key insight for future similar issues]
### Issue: [Another implementation challenge]
...
## Quick Workarounds
- [Temporary solution for common issue] - [why needed]
- [Dependency/gotcha discovered] - [how it affects work]
## Open Questions
- [Unresolved question - from Step 5 deferred decisions OR from code/comments]
- [Uncertainty needing resolution]
- **[Decision Topic]**: [Context and options to consider - from Step 5 deferred decisions]
- Research available: [Link to research-[topic].md if "Perform research" was selected]
## Quick Tips for Next Agent
- [Time-saving tip from implementation challenges]
- [Gotcha to watch out for]
- [Effective approach that worked]
PLAN.md Structure:
Note: All dates and timestamps in PLAN.md must use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
Generate timestamp with: date -u +"%Y-%m-%dT%H:%M:%SZ"
# Work Plan - [Project Name]
**Created**: [Use actual timestamp from `date -u +"%Y-%m-%dT%H:%M:%SZ"` on first creation, preserve on updates]
**Updated**: [Use actual timestamp from `date -u +"%Y-%m-%dT%H:%M:%SZ"`]
**Status**: [In Progress/Blocked/Complete]
## Goals & Objectives
### Primary Goal
[From Background & Context]
### Success Criteria
- [ ] [Measurable criterion from Goals & Objectives]
- [ ] [Another criterion]
## Task Breakdown
### Phase 1: [Phase Name] (Status: Completed/In Progress/Pending)
**Goal**: [What this achieves]
Tasks:
- [x] [Completed task from git commits or completed todos]
- [x] [Completed task from TodoRead marked completed]
- [ ] [In-progress task from modified files or in_progress todos]
- [ ] [In-progress task from TodoRead marked in_progress]
- [ ] [Planned task from TODO comments or pending todos]
- [ ] [Planned task from TodoRead marked pending]
- [ ] [Decision-driven task from Step 5 finalized decisions]
- [ ] βΈοΈ [Blocked task] - Blocked by [decision from Step 5]
### Decisions & Research
- β οΈ **DECISION REQUIRED**: [Topic from Step 5 deferred decisions] - See NOTES.md Open Questions
- π **RESEARCH AVAILABLE**: Review research-[topic].md and decide on [topic from Step 5 "Perform research" selections]
### Phase 2: [Next phase...]
## Dependencies
### External
- [Package/service] - [what provides] - [status]
### Internal
- [File/module] needs [other file] first
- [Decision] needed before [task]
## Risks & Mitigation
### Risk: [From FIXME/HACK comments]
**Impact**: [High/Medium/Low]
**Mitigation**: [Strategy]
## Decision Log
### Decision: [What was decided]
**Date**: [Use actual timestamp from `date -u +"%Y-%m-%dT%H:%M:%SZ"` or extract from commit date]
**Rationale**: [why - from Key Decisions]
Output Format:
[β
] Handover: $ARGUMENTS
## Summary
- Context file: [path to CONTEXT.md]
- Notes file: [path to NOTES.md]
- Plan file: [path to PLAN.md]
- Files classified: [count]
- Completed: [count] | In Progress: [count] | Planned: [count]
- Implementation notes: [X issues resolved, Y workarounds, Z tips]
- Plan tasks: [count] across [phases] phases
- Recent commits analyzed: [count]
- Todos incorporated: [count from TodoRead] ([completed]/[in_progress]/[pending])
- **Decisions consulted: [count identified] ([finalized]/[deferred]/[researched])**
- **Plan updates: [count decision-driven tasks added], [count blocked tasks identified]**
- **Research files generated: [count] - [list of research-[topic].md files]**
## Document Sections
### CONTEXT.md
- Background & Context: β/X
- Goals & Objectives: β/X
- Reference Documents: β/X
- Current State: β/X
- File Status: β/X
- Recent Changes: β/X
- Key Decisions: β/X
- Next Steps: β/X
### NOTES.md
- Implementation Issues: β/X
- Quick Workarounds: β/X
- Open Questions: β/X
- Quick Tips: β/X
### PLAN.md
- Goals & Success Criteria: β/X
- Task Breakdown: β/X
- Dependencies: β/X
- Timeline: β/X
- Risks & Mitigation: β/X
## File Status Breakdown
### β
Completed ([count])
[first 3 files...]
### π§ In Progress ([count])
[all in-progress files...]
### π Planned ([count])
[all planned files...]
## Next Steps Identified
1. [immediate next action]
2. [following action]
## Notes
- [Any important observations]
- [Suggestions for continuation]
/handover
# Creates 3 files with current project state:
# - CONTEXT.md: Status, files, decisions
# - NOTES.md: Implementation issues encountered
# - PLAN.md: Goals, tasks
/handover sprint1
# Creates or updates:
# - sprint1-CONTEXT.md: Current status and decisions
# - sprint1-NOTES.md: Implementation insights and solutions
# - sprint1-PLAN.md: Goals and task breakdown
/handover
# If files exist, updates them with:
# - New timestamp
# - Refreshed current state
# - Updated file classifications
# - New recent changes appended
/handover sprint1/phase
# Error: Invalid prefix format (contains slashes)
# Suggestion: Use simple prefix like 'sprint1' or '/handover' for default
/handover
# Error: Not a git repository
# Suggestion: Initialize git with 'git init' or navigate to a git repository
After running /handover, three complementary files work together:
1. Read CONTEXT.md first β Understand current status
2. Read NOTES.md second β Learn from implementation
3. Read PLAN.md third β Know the path forward
This trio provides complete project understanding for seamless continuation.
The /takeover command automatically reads all three handover files to provide complete project understanding for seamless continuation: