handover

Handover Document Generator

Generate a self-contained context transfer document that allows a fresh agent to continue this session's work. The receiving agent has no access to this conversation — every reference must be complete and verifiable.

Arguments

Parse $ARGUMENTS for:

• focus-area (optional): Narrow the handover to a specific topic (e.g., "authentication", "database")
• --brief: Produce a short summary instead of the comprehensive document

Step 1: Ground Truth

Verify actual repository state before analyzing the conversation:

git status
git log --oneline -10
git diff --stat HEAD~3..HEAD 2>/dev/null || git diff --stat

Reflect on whether the git state matches your session memory. Note any discrepancies — they indicate uncommitted work, reverted changes, or stale assumptions.

Step 2: Reconstruct the Session

Analyze the conversation to capture: the original goal and underlying motivation, key decisions with rationale and rejected alternatives, implementation sequence and obstacles encountered, implicit knowledge and gotchas discovered, and where work stopped.

Focus on the WHY behind decisions — a fresh agent can read the code to see WHAT exists, but needs the handover to understand WHY it exists.

• Original Goal: What the session set out to accomplish and the underlying motivation
• Key Decisions: Significant choices where alternatives existed, with rationale and what was rejected
• Progress: What was planned, what was completed (with file references like path/file.ts:123), what remains
• Challenges: Obstacles that affected the approach and how they were resolved
• Current State: Modified files, git status, branch, uncommitted changes, environment/dependencies
• Context for Continuation: Implicit knowledge, gotchas, reasoning chains, and user preferences that aren't obvious from the code
• Next Steps: Numbered, specific, actionable (e.g., "Run bun test to verify auth changes" rather than "Test the changes")