Session Handoff

Session Handoff is an AI skill that manages the transfer of context, state, and conversation history between AI assistant sessions or between human team members during shift changes. It covers context summarization, state serialization, priority flagging, handoff note generation, and continuity protocols that ensure no information is lost during transitions.

What Is This?

Overview

Session Handoff provides structured approaches to transferring work context between sessions or team members. It handles summarizing conversation history into actionable handoff notes, serializing session state including pending tasks and decisions, flagging unresolved issues with their investigation status, generating structured handoff documents with priority rankings, preserving file references relevant to ongoing work, and verifying that handoff recipients have necessary context.

Who Should Use This

This skill serves AI assistant users managing complex multi-session projects, operations teams performing shift handoffs for on-call rotations, engineering teams passing work in progress between time zones, and project managers tracking task continuity across team members.

Why Use It?

Problems It Solves

Long running projects lose context when sessions end or team members rotate, forcing participants to reconstruct state from scattered notes. Critical details about investigation progress and decisions get lost in transition. Without structured handoff protocols, incoming members waste time on questions already answered.

Core Highlights

Automated context summarization distills session histories into concise actionable notes. State serialization captures task status, pending decisions, and blockers in structured format. Priority flagging ensures urgent items receive immediate attention after handoff. Verification checklists confirm the recipient has necessary context.

How to Use It?

Basic Usage

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class HandoffNote:
    session_id: str
    timestamp: datetime
    summary: str
    pending_tasks: list
    decisions_made: list
    blockers: list
    file_references: list
    priority: str = "normal"

class HandoffGenerator:
    def __init__(self, session_log):
        self.log = session_log
        self.notes = []

    def extract_tasks(self):
        tasks = []
        for entry in self.log:
            if entry.get("type") == "task":
                tasks.append({
                    "description": entry["content"],
                    "status": entry.get("status", "pending"),
                    "context": entry.get("context", "")
                })
        return tasks

    def extract_decisions(self):
        return [
            entry["content"]
            for entry in self.log
            if entry.get("type") == "decision"
        ]

    def generate(self):
        return HandoffNote(
            session_id=self.log[0].get("session_id", ""),
            timestamp=datetime.now(),
            summary=self.build_summary(),
            pending_tasks=self.extract_tasks(),
            decisions_made=self.extract_decisions(),
            blockers=self.extract_blockers(),
            file_references=self.extract_files()
        )

    def build_summary(self):
        task_count = len(self.extract_tasks())
        blocker_count = len(self.extract_blockers())
        return (f"{task_count} tasks pending, "
                f"{blocker_count} blockers identified")

    def extract_blockers(self):
        return [e["content"] for e in self.log
                if e.get("type") == "blocker"]

    def extract_files(self):
        return [e["path"] for e in self.log
                if e.get("type") == "file_reference"]

Real-World Examples

class ShiftHandoff {
  constructor(outgoingNotes, systemStatus) {
    this.notes = outgoingNotes;
    this.status = systemStatus;
  }

  generateReport() {
    return {
      timestamp: new Date().toISOString(),
      activeIncidents: this.status.incidents.filter(
        (i) => i.status !== "resolved"
      ),
      pendingActions: this.notes.filter(
        (n) => n.status === "pending"
      ),
      recentChanges: this.status.deployments
        .filter((d) => this.isRecent(d.timestamp))
        .map((d) => ({
          service: d.service,
          version: d.version,
          deployer: d.author,
        })),
      watchItems: this.notes
        .filter((n) => n.priority === "watch")
        .map((n) => n.description),
    };
  }

  isRecent(timestamp) {
    const hours = 8;
    const cutoff = Date.now() - hours * 3600 * 1000;
    return new Date(timestamp).getTime() > cutoff;
  }

  verifyHandoff(incomingAcknowledgment) {
    const required = ["incidents", "pending", "changes"];
    const acknowledged = incomingAcknowledgment.sections || [];
    const missing = required.filter(
      (r) => !acknowledged.includes(r)
    );
    return { complete: missing.length === 0, missing };
  }
}

Advanced Tips

Include a "state of mind" section that captures your current hypothesis about ongoing investigations. Link directly to specific file paths and line numbers rather than describing code locations in prose. Establish a maximum handoff note length to force prioritization.

When to Use It?

Use Cases

Use Session Handoff when continuing complex multi-session projects with an AI assistant, when performing on-call shift changes that require operational context transfer, when transitioning project ownership between team members, or when documenting investigation progress on multi-day debugging efforts.

Related Topics

Incident management runbooks, operational playbooks, knowledge management systems, project status reporting, and team communication protocols complement session handoff practices.

Important Notes

Requirements

A structured log or notes from the outgoing session or shift. A handoff template agreed upon by the team for consistent format. Enough overlap time for the incoming participant to ask clarifying questions.

Usage Recommendations

Do: write handoff notes as you work rather than reconstructing them at the end of a session. Include both what was attempted and what the results were, not just the final state. Flag items that need immediate attention separately from background context.

Don't: include every detail from a long session, as the recipient needs actionable highlights rather than a transcript. Assume the incoming person has the same context you do, because information you consider obvious may not be. Skip the handoff process when time is short, as incomplete transitions create more work downstream.

Limitations

Automated summarization may miss nuance that a human would recognize as important. Handoff quality depends on the outgoing participant documenting consistently throughout their session. Complex technical investigations involve mental models that are difficult to transfer through written notes.