Generate Handover

Skill: Generate Handover

What This Skill Does

This documentation shall serve Agents and Humans when working in consecutive sessions with the project. Creates a session handover document (plans/<name>/handovers/session-<date>.md) that captures everything a new session needs to continue work seamlessly:

• What was accomplished in this session
• What is in progress (interrupted work)
• Key decisions made and their rationale
• Current state of modified files
• Blockers and issues discovered
• Concrete next steps
• Context that would be lost without the handover

When to Use

• When the user asks to "create a handover" or "save session state"
• When ending a work session on a multi-phase plan
• When work is interrupted and will be continued later
• When switching between team members or agents

Do NOT generate handovers automatically. This skill is invoked manually by the user.

Execution Model (Recommended)

• Preferred: the primary agent runs this skill and writes the handover under plans/<name>/handovers/.
• Rationale: a handover is a distilled session narrative (decisions, rationale, state). It should be authored where the session context lives.
• Optional: delegate git status/git diff --stat interpretation or bulk file listing to doc-explorer, but keep narrative/decisions in the primary.

Workflow

Step 1: Identify the Context

Determine what to capture:

• Which plan is being worked on? Check plans/ directory
• What phase is active? Read plan.md and todo.md
• If no formal plan exists, create a standalone handover (see below)

Step 2: Gather Session Information

Collect from the current session context:

Progress:

• What tasks were completed? (from todo list changes, commits, conversation)
• What is currently in progress? (incomplete work, partial implementations)
• What was planned but not started? (remaining todo items)

Decisions:

• What technical decisions were made? (architecture, library choices, approach)
• What alternatives were considered? (and why they were rejected)
• What trade-offs were accepted?

Implementation State:

• Which files were modified? Use git diff --stat or git status
• Are there uncommitted changes?
• What tests are pending?

Issues:

• Are there blockers? (dependencies, unclear requirements, technical issues)
• Were workarounds applied that need revisiting?

Step 3: Write the Handover Document

Create plans/<name>/handovers/session-<YYYY-MM-DD>.md:

If multiple handovers on the same day, append a counter: session-2025-02-14-2.md.

Fill in all sections from the template:

1. Session Summary: 2-3 sentences describing what this session was about
2. Progress: Organized by completed / in-progress / not-started
3. Key Decisions: Table with decision, alternatives considered, and rationale
4. Current State: Modified files with what changed, pending tests
5. Blockers & Issues: What prevents progress, with potential solutions if known
6. Next Steps: Ordered list of what the next session should do first
7. Context for Next Session: Free-form section for anything that would be lost - partial reasoning, important constraints discovered, "watch out for" notes

Step 4: Update the Todo List

After creating the handover:

• Ensure todo.md reflects the actual current state
• Mark completed items
• Add any newly discovered items
• Note blockers

Step 5: Confirm with User

Use the question tool to ask:

• Is anything missing from the handover?
• Are the next steps correctly prioritized?

Standalone Handovers (No Plan)

If there is no formal plan but a handover is needed:

• Create docs/handovers/session-<date>.md (in the docs directory instead of plans)
• Omit plan/phase references from the frontmatter
• Focus on the general session context, decisions, and next steps

Rules

1. Accuracy over completeness: Only document what actually happened. Don't invent or assume progress.
2. Concrete next steps: "Continue working on auth" is useless. "Implement the JWT refresh token rotation in src/auth/refresh.ts, starting from the rotateToken function stub" is actionable.
3. Decision rationale matters: Capture why decisions were made, not just what was decided. The next session needs the reasoning to avoid re-evaluating the same options.
4. File-based interface: The handover document is the interface. All context goes into the file, not into chat messages.
5. Don't duplicate the todo list: Reference todo.md for task status. The handover captures session context (decisions, state, blockers), not a repeat of the task list.
6. Use git for file state: Use git status and git diff --stat to identify modified files rather than relying on memory.
7. Multiple handovers are normal: Each session can produce its own handover. They are additive, not replacements.
8. Keep it scannable: The next session's agent will read this to bootstrap context. Use clear headings, short bullet points, and tables where appropriate.
9. Todo updates stay lightweight: When updating todo.md in Step 4, make simple status changes directly. For complex plan restructuring, the update-plan skill should be used instead.

Templates

This skill includes a normative template as a bundled file. Only read the templates when processing them. Output MUST follow the template headings and frontmatter keys:

• tpl-session-handover.md - Structure for handover documents