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