Handoff

Handoff

Create summaries that enable a fresh instance to continue work seamlessly with no prior context.

When To Use

• Conversation is approaching context window limits and work must continue
• User explicitly requests a session summary or handoff document
• Preparing to transfer work to another agent instance or a fresh session
• Archiving a complex session for future reference or resumption

Boundaries

• Not for generating project documentation, READMEs, or changelogs
• Not for summarizing external documents or articles unrelated to the session
• Skip when the session is trivial (single question-answer with no ongoing state)
• Do not include sensitive credentials or secrets in the summary file

Verification

• Summary is written to docs/sessions/HANDOFF_{SESSION-NAME}_{YYYY-MM-DD}.md
• All 9 numbered sections are present (use "None" for inapplicable sections)
• File paths are absolute and code snippets include language identifiers
• A fresh agent instance could resume work from the summary without clarifying questions

Core Goal

Answer: "If I were dropped into this conversation cold, what would I need to pick up exactly where we left off?"

Output File Location

Write the session summary to: docs/sessions/HANDOFF_{SESSION-NAME}_{YYYY-MM-DD}.md

Determining SESSION-NAME automatically: Derive a concise, descriptive name (2-4 words, kebab-case) from the session context:

• Primary feature or component being worked on (e.g., "user-auth", "payment-flow")
• Main bug or issue addressed (e.g., "websocket-reconnect", "memory-leak")
• Technology or tool focus (e.g., "pdf-processing", "react-migration")
• Type of work if mixed topics (e.g., "dashboard-refactor", "api-integration")

Examples:

• Bug fix session → "react-profile-bug"
• Feature work → "realtime-notifications"
• Refactoring → "state-management-refactor"
• Multiple small tasks → "miscellaneous-fixes"

File creation steps:

1. Determine the project root directory (where the user is working)
2. Derive SESSION-NAME from the session context
3. Get current date in YYYY-MM-DD format
4. Create docs/sessions/ directory if it doesn't exist
5. Write summary to docs/sessions/HANDOFF_{SESSION-NAME}_{YYYY-MM-DD}.md
6. Inform user of the file location

Summary Structure

Generate summaries with these 9 numbered sections:

1. Primary Request and Intent

• User's high-level goals and problem being solved
• Desired end state and constraints/preferences expressed
• Focus on intent, not just literal requests

2. Key Technical Concepts

• Technologies, frameworks, libraries in use
• Architectural patterns or conventions
• Project-specific terminology

3. Files and Code Sections

For each modified or relevant file:

• Full absolute path - Brief description
• What was changed and why
• Key code snippets with language identifiers

// Include enough context to understand the change

4. Errors and Fixes

For any bugs encountered:

• Symptom: What the user observed
• Root Cause: Why it happened (be specific)
• Solution: What was changed and why it works
• Include before/after code when relevant

5. Problem Solving Approach

• Why was approach X chosen over Y?
• What alternatives were considered?
• What assumptions were made?

6. User Messages

• Preserve exact user requests in chronological order
• Quote directly when phrasing matters
• These are ground truth for understanding intent

7. Pending Tasks

List incomplete work with enough detail to resume:

• What specific steps remain?
• What files need modification?
• What was the next immediate action?

8. Current Work State

• What file was being edited?
• What line or function was in progress?
• What was the most recent tool call or action?

9. Suggested Next Step

Provide a single concrete action to resume:

• Be specific enough to execute immediately
• Reference exact file paths and function names

Critical Requirements

Prioritize Resumability

• Future instance should continue without clarifying questions
• Include enough code context for edits without re-reading entire files
• Preserve error messages and stack traces verbatim

Be Precise, Not Verbose

• Use exact file paths, function names, line numbers
• Quote code directly rather than paraphrasing
• Avoid vague descriptions like "updated the file" — say what changed

Track State, Not Just History

• Distinguish completed vs. in-progress vs. pending work
• Note committed vs. uncommitted changes if git available
• Preserve todo list state if one exists

Preserve User Voice

• Keep user's exact phrasing for requirements
• Note implicit preferences (coding style, communication style)
• Record any corrections or clarifications provided

Format Conventions

• Use markdown with clear headers
• Code blocks with syntax highlighting
• Bold for file paths and key terms
• inline code for function/variable names
• Write "None" for inapplicable sections rather than omitting them

The summary should feel like watching a fast-forward of the entire session.

Template

See assets/summary-template.md for a blank template to start from.

Sibling skills

Four knowledge-capture skills, distinguished by scope and timing:

• session-retro — append non-obvious learnings into existing project reference docs at session end. Different output: this skill produces a fast-forward summary, that one routes facts into reference files.
• compound-docs — categorize a confirmed solution under docs/solutions/. Different shape: solution-document, not session-summary.