session-handoff

Skill: Session Handoff

Purpose

Preserve critical state when a session approaches context limits, so the next session (or /resume-pipeline) can pick up seamlessly. Prevents lost work when context compaction occurs or the user starts a new conversation.

When to Apply

Automatically when:

• A long multi-step workflow is in progress
• A multi-step Google Workspace workflow is in progress
• The pipeline involves external resource IDs (doc IDs, slide IDs, Drive folders)
• Before any pause point where the user might come back later

---

What to Save

Write to the EXACT path working/session_state.yaml (not session_state_handoff.yaml or any variant). The /resume-pipeline command looks for this specific file path.

This file MUST be comprehensive, regardless of how simple the handoff seems. Capture ALL of the following information:

Required Fields (always include):

• ✅ Dataset name and connection details
• ✅ Task description (what analysis/work is in progress)
• ✅ Pipeline progress (what's complete, what's next)
• ✅ All external resource IDs (Google Docs, Slides, Drive files) with URLs
• ✅ Local file inventory (working/ and outputs/ directories)
• ✅ Auth state (user email, last verified date)
• ✅ Known issues or blockers (write "None" if no issues)
• ✅ Resume instructions (step-by-step guide)

---

The Template (Use This Every Time)

Use the complete template. Fill every section (an empty section is "None"), because the next session has no other context.

Template:

# Session State — auto-generated by session-handoff skill
# Last updated: {{DATE}} {{TIME}}

dataset: "{{DATASET_NAME}}"
task: "brief description of what we're doing"

# External resource IDs (Google Workspace, etc.)
resources:
  google_doc:
    id: "18MTagnf_z5..."
    title: "Document Title"
    url: "https://docs.google.com/document/d/18MTagnf.../edit"
    status: "content complete, needs formatting review"
  google_slides:
    id: "1in6mkRf..."
    title: "Deck Title"
    url: "https://docs.google.com/presentation/d/1in6mkRf.../edit"
    status: "12 slides built, reviewer passed"
  drive_folder:
    id: "1PV9ols..."
    name: "Folder Name"
  drive_files:
    - id: "1abc..."
      name: "01_chart.png"
    - id: "2def..."
      name: "02_chart.png"

# Pipeline progress
pipeline:
  last_completed_step: "chart generation"
  current_step_status: "narrative draft 80% complete — context and findings done, recommendations need 2 more paragraphs"  # Use this for partially-complete steps
  next_step: "Google Doc creation"
  steps_remaining:
    - "Create Google Doc with proper image placement"
    - "Run Google Doc Reviewer"
    - "Final review of both deliverables"

# Local file inventory
local_files:
  charts:
    - outputs/charts/01_height_crossover.png
    - outputs/charts/02_height_gap.png
  data:
    - outputs/ms_case_study/data.csv
  working:
    - working/narrative_draft.md
    - working/storyboard.md

# Auth state (REQUIRED)
auth:
  google_email: "[email protected]"  # If not provided by user, check working files or note "unknown — verify at resume"
  last_verified: "2026-03-05"
  notes: "Tokens expire between sessions — expect re-auth"

# Known issues or blockers (REQUIRED — use "None" if no issues)
issues:
  - "Google Doc images overlap with text — needs rebuild with proper placement"
  - "Doc heading formatting was applied manually, may need re-check"
  # OR if no issues:
  # - "None — all work completed successfully"

# Resume instructions (REQUIRED)
resume:
  command: "/resume-pipeline"
  steps:
    - "Verify auth for {{auth.google_email}}"
    - "Load external resources"
    - "Continue from: {{pipeline.next_step}}"