SethGammon/session-handoff

/session-handoff — Context Transfer

Orientation

Use when ending a session and wanting to preserve context for the next one. Also used automatically by orchestrators (Archon, Fleet) at session boundaries.

Don't use when: You want to extract reusable patterns from a completed campaign (use /learn), write a structured postmortem for a failed campaign (use /postmortem), or produce documentation rather than a context transfer.

Protocol

1. Collect session data (run in parallel):

   • git log --oneline -20 and git diff HEAD --stat
   • Read .planning/campaigns/ for files with status: active
   • Read .planning/fleet/ for files with status: active or needs-continue

2. Identify the primary thread: If an active campaign exists, use its current phase as the anchor. If multiple campaigns are active, list each. If no campaign, use the most recent git commits as the frame.

3. Map data to HANDOFF fields:

   • What changed: campaign phase output if campaign active; otherwise commit subjects from this session
   • Key decisions: commit messages with a tradeoff word ("instead", "because", "not"); or explicit statements from the conversation
   • Unresolved items: campaign items marked blocked or parked; TODOs added this session; anything explicitly deferred
   • Next steps: campaign's next phase if active; otherwise the top open item from above

4. Output the HANDOFF block.

Output Format

---HANDOFF---
- {what was built or changed — be specific}
- {key decisions and tradeoffs — include reasoning}
- {unresolved items — what's blocking}
- {next steps — what the next session should do first}
---

Keep it to 3-5 bullets, under 150 words. This is a context transfer, not a report.

Quality Gates

• Every bullet must be actionable or informative
• No vague statements ("made progress on X")
• Specific file references where relevant
• Decisions include reasoning, not just the choice

Fringe Cases

.planning/ does not exist: Skip campaign and fleet checks. Treat as "no active campaigns" and proceed with git-only context.

Corrupted or unparseable campaign file (malformed frontmatter, invalid status, or truncated content in .planning/campaigns/): Skip that file and treat it as inactive. Output: "Campaign file at {path} could not be parsed — treating as inactive. Check the file manually if this is unexpected."

No active campaign and no git changes: If there is nothing to summarize, say so explicitly: "No active campaign or session changes found. Nothing to hand off." Do not fabricate a handoff.

No context to summarize (fresh session with no edits): Output a minimal handoff noting the session start state. At minimum, include what the user asked about and what was found.

Campaign is in a blocked/parked state: Include the block reason and the recommended next action in the handoff so the next session can resume immediately.

Contextual Gates

Reversibility: Green — this skill writes nothing to disk; the HANDOFF block is display-only. Cost: No cost actions — synthesis only; no agents spawned, no confirmation needed. Trust: No gates — safe at all trust levels.

Exit Protocol

Output the HANDOFF block and then wait for the next command. This skill does not write to disk — the HANDOFF block is the deliverable, for the user to copy into the next session or save manually.