session-handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

# Session Handoff

## Overview

Generate a self-contained prompt that lets a fresh Claude Code session resume where this one left off.

Git, files, and memory are already recoverable by the next session — it starts with CLAUDE.md, memory, and full tool access. What's NOT recoverable is session-specific context: decisions, rejected approaches, gotchas, in-flight tasks. Focus the handoff on that.

**Reference:** implements the "Clear with a distilled brief" pattern from [Anthropic's session management guide](https://claude.com/blog/using-claude-code-session-management-and-1m-context).

## When to Use

- User says "handoff", "session summary", "wrap up", or "generate handoff"
- Context rot is degrading quality — responses are slower, less precise, or missing earlier instructions (see "When to Initiate" below)
- Switching to a different machine or IDE
- Before taking a break on multi-session work
- After correcting Claude 2+ times on the same issue (the context is polluted with failed approaches — `/clear` with a handoff is better than continuing)

**Short-circuit:** If the session involved no code changes, no decisions, and no in-flight work, skip the handoff and tell the user: "This session has no state worth handing off. Git and memory are up to date."

## Procedure

### Step 1: Gather Baseline State

Quick git snapshot (parallel, read-only):

```bash
git branch --show-current
git log --oneline -5
git status --short
git remote -v
```

Read project memory files — Claude Code loads these automatically at session start from `~/.claude/projects/<project-path>/memory/`. Check MEMORY.md for the index and read referenced files to assess staleness.

Check for pending/in-progress tasks via the current Claude Code task-tracking tool (TaskList on current builds, TodoWrite on older builds — whichever is exposed in this session). If tasks exist, weave them into "What We Were Doing" and "Next Steps" rather than listing separately. Summarize rather than enumerate if there are more than 3. If neither tool is available, skip this check — the skill does not depend on it.

### Step 2: Reflect on Session Context

This is the critical step. Review the conversation and identify:

- **Decisions made** — architectural choices, trade-offs, "we decided X because Y"
- **Approaches tried and rejected** — what didn't work and why (saves the next session from repeating dead ends)
- **Key findings** — bugs found, root causes identified, surprising behaviors observed
- **In-flight work** — what's partially done, what's next, what's blocked
- **Mental model** — any non-obvious understanding built up about the codebase, system, or problem domain that isn't in docs or code
- **External context** — Slack threads, PRs, incidents, or people referenced during the session

Use judgment about what matters. A session that was 90% debugging one issue needs different handoff content than a session that touched five files across three features.

**Quality check:** If you removed "What Didn't Work" and "Key Findings" from your notes, would everything remaining be recoverable from `git log` and file contents? If yes, you haven't reflected deeply enough — go back and find the non-obvious context.

### Step 3: Update Memory

Before generating the prompt, persist anything the next session should know long-term:

1. Read existing memory files
2. Update stale memories (branch moved, bug fixed, status changed)
3. Add new memories for significant learnings not yet persisted
4. Update MEMORY.md index if files changed

**Memory-worthy vs ephemeral — examples:**
- **Save to memory:** "The deploy service requires PCSK JIT access for gov accounts — not documented anywhere." (Persistent fact, useful across sessions.)
- **Keep in handoff only:** "Tried using `sed` to fix the config but escaping was wrong; switched to Python." (Debugging dead end — useful for the next session, not long-term.)
- **Ask the user:** "The `cdk deploy` takes 12 minutes in stg." (They may already know this.)

For straightforward factual updates, just do it. For ambiguous or sensitive findings, ask the user first.

### Step 4: Generate Handoff Prompt

Build a markdown block. Include only sections that have meaningful content — omit empty sections rather than padding with "None". **Target 200-500 words** — every word competes with CLAUDE.md, project rules, and memory for context in the new session.

````markdown
```
## Continue [describe the work, not the project name] 

### Working Directory
<cwd>

### Read First
- <2-4 files that give the fastest orientation — README, active spec, key source file>
- <include memory path if memories were updated>

### Current State
- Branch: <branch> (latest: <short sha> "<commit msg>")
- Uncommitted: <clean | summary of changes>

### What We Were Doing
<1-3 sentences describing the current task and where it stands>

### Decisions Made
- <decision and rationale — the WHY matters more than the WHAT>

### What Didn't Work
- <approach tried, why it failed — prevents the next session from repeating>

### Key Findings
- <non-obvious things learned that aren't captured in code or memory>

### Next Steps
1. <most immediate next action>
2. <follow-up tasks>

### Git Workflow
- Push: `git push <remote> <branch>`
- Commit prefix: <convention if applicable>
```
````

**Guidelines:** brief a colleague at your desk. Specifics — file paths, function names, errors — not summaries. "What Didn't Work" is often the highest-value section. If the session was a quick fix, 5 lines is plenty; don't pad.

**Self-check:** could a fresh session reading only this plus CLAUDE.md resume productively? If not, add the missing context.

### Step 5: Output, Save, Copy

1. **Display** the fenced markdown block in the conversation.
2. **Save to log** at `~/.claude/data/session-handoff/logs/handoff-<YYYY-MM-DDTHH-MM-SS>.md` — dashes only (colons break filenames), `mkdir -p` if needed. User-data dir, not the plugin tree, so logs survive reinstalls.
3. **Copy to clipboard** — pipe the saved log into the first tool the host has:
   ```bash

From neurot1cal/bdigital-public, MIT.

More from neurot1cal/bdigital-public