git:20260827.7ff2e25 to git:20260902.b370de6

6 added, 14 removed. Audit A to A.

---

- description: Preserve critical state when a session approaches context limits so the next session can pick up seamlessly. Use this skill whenever you're in a long workflow (15+ tool calls), working with Google Workspace resources (Docs, Slides, Drive), creating external resources that have IDs you need to track, running multi-step pipelines that might need to be resumed, approaching context limits, or when the user says things like "save state", "let's pause", "I'll come back later", "save progress", "I need to stop for now", "bookmark this", "save my work", or when you detect that a workflow involves multiple phases and the user might return later. This skill is CRITICAL after creating Google Docs, Slides, or Drive files — those resource IDs are impossible to recover if lost. Also apply proactively during analysis pipelines after major phases complete (data exploration done, charts generated, narrative written, deck created) so users can resume at natural checkpoints. Write session state immediately after any external resource creation, not just at the end. If you're building a deck and it takes 10+ tool calls, save state halfway through. If context is getting long and you haven't saved state yet, do it now before you forget. This prevents lost work when context compaction occurs or users start new conversations.

+ description: Preserve critical state when a session approaches context limits so the next session can pick up seamlessly. Use this skill whenever you're in a long, multi-step workflow, working with Google Workspace resources (Docs, Slides, Drive), creating external resources that have IDs you need to track, running multi-step pipelines that might need to be resumed, approaching context limits, or when the user says things like "save state", "let's pause", "I'll come back later", "save progress", "I need to stop for now", "bookmark this", "save my work", or when you detect that a workflow involves multiple phases and the user might return later. This skill is CRITICAL after creating Google Docs, Slides, or Drive files — those resource IDs are impossible to recover if lost. Also apply proactively during analysis pipelines after major phases complete (data exploration done, charts generated, narrative written, deck created) so users can resume at natural checkpoints. Write session state immediately after any external resource creation, not just at the end. If context is getting long and you haven't saved state yet, do it now before you forget. This prevents lost work when context compaction occurs or users start new conversations.

---

# 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:

- - Context is getting long (15+ tool calls in a single workflow)

+ - 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)

- **Always use this complete template structure.** Even if the handoff seems simple (e.g., just one Google Doc ID), fill out ALL sections. A comprehensive state file is always better than a minimal one — it ensures the next session has full context.

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

**Template:**

```yaml

# 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..."

drive_files:

- id: "1abc..."

- id: "2def..."

# 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: "user@example.com" # 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}}"

```

- **Important:** Even if the handoff seems simple (e.g., just saving one Google Doc ID), fill out ALL sections of this template. A comprehensive state file is always better than a minimal one — it ensures the next session has full context.

---

## When to Write

### Proactive triggers (write automatically):

- After creating any Google resource (doc, slides, Drive file)

- After completing a major pipeline phase (analysis, charting, doc creation)

- - When conversation reaches ~20 tool calls

+ - After any long stretch of tool calls in one workflow (the same trigger as "When to Apply" above)

- Before any operation that might run long (batch chart generation, etc.)

### Reactive triggers (write when prompted):

- User says "save state", "let's pause", "I'll come back later"

- Context compaction warning from the system

- `/resume-pipeline` is likely needed

---

## How to Resume

At session start, check for existing state:

1. Read `working/session_state.yaml` if it exists

2. Verify external resources still exist (quick API call to check doc/slides)

3. Check auth (run auth-preflight skill)

4. Report status to user:

```

Resuming from previous session:

- Google Doc: [title] — [status]

- Google Slides: [title] — [status]

- Charts: [N] uploaded to Drive

- Next step: [description]

- Auth: [OK/needs re-auth]

```

---

## Rules

1. **Write state after every external resource creation.** A Google Doc ID is

impossible to recover if lost — save it immediately.

2. **Include URLs, not just IDs.** The user needs clickable links to verify

their resources.

3. **Describe status in plain English.** "content complete, needs formatting

review" is more useful than a boolean flag.

- 4. **Keep the file small.** Only save what's needed to resume. Don't dump

- entire analysis narratives — reference the file paths instead.

+ 4. **Reference, don't copy.** Point at file paths instead of pasting narratives

+ or data into the state file.

5. **Overwrite, don't append.** Each write is a complete snapshot. The file

should reflect current state, not a history log.

6. **Auth email is critical state.** Always include the exact email used for

Google Workspace MCP calls — this is the #1 source of auth failures. If the

user hasn't mentioned their email, check for it in working files or previous

MCP calls. If truly unknown, note "email unknown — verify at resume time".

- 7. **Be comprehensive, not minimal.** Even if only one resource ID needs saving,

- fill out the complete template. Include dataset, task description, pipeline

- progress, and resume instructions. Future you (or the next session) will

- thank you for the extra context. Think of this as a "save game" file — capture

- everything needed to restore the exact state.