session-handoff

Session-Handoff — Compact State for Session Transfer

Register: TECHNIQUE Goal: Preserve task continuity across session boundaries. Next session reads handoff doc and continues without loss of context. Constraints: Handoff doc must be machine-readable (next agent loads it, not just humans). Include all open decisions and evidence anchors produced so far. Commit before session ends. Adapt: depth of handoff to task complexity — a 2-hour session needs more than a 15-minute one.

When to use:

• Session approaching token budget limit mid-task
• Switching agent (different model, different harness)
• Handing off to another developer's agent session
• Long task that will need multiple sessions
• End of day, task incomplete

Distinguish from:

• adr-commit → branch-level closure (task COMPLETE, merging)
• knowledge-compound → cycle-level extraction (sprint COMPLETE, extracting learnings)
• session-handoff → session-level state capture (task IN PROGRESS, continuing later)

Announce: "Using session-handoff to capture current state before session ends."

---

Pre-Check

# Current branch and recent commits:
!git log --oneline -5 2>/dev/null

# Open specs and plans:
!ls docs/superskills/specs/ docs/superskills/plans/ 2>/dev/null

# Any SPEC_APPROVED specs in progress:
!grep -rl "SPEC_APPROVED: true" docs/superskills/specs/ 2>/dev/null

---

The Handoff Document

Save to: docs/superskills/session-state-YYYY-MM-DD-HH.md

# Session Handoff — [YYYY-MM-DD HH:MM]

## Task Summary
[1-2 sentences: what we're building and why]

## Current Status
STATUS: IN_PROGRESS | BLOCKED | WAITING_FOR_REVIEW

## Completed Steps
[Bullet list of what was done this session — be specific, include file paths]
- ✅ [Step]: [outcome] — Evidence Anchor: [command + result if applicable]
- ✅ [Step]: [outcome]

## Open Work
[What remains to be done — ordered by dependency]
- [ ] [Next step] — depends on: [prerequisite if any]
- [ ] [Step after that]

## Open Decisions
[Questions that arose but weren't resolved — next session must address these]
- ❓ [Decision]: [context] — Options: [A] vs [B] — Lean: [current thinking]

## Active Context
SPEC: [path to spec file if exists]
PLAN: [path to plan file if exists]
BRANCH: [current git branch]
CONSTITUTION_LAWS_ACTIVE: [any constitution rules especially relevant to remaining work]

## Evidence Produced This Session
[Evidence Anchors already established — next session doesn't need to re-verify]
- [File:line] — [what was verified] — [Evidence Tier T1/T2]

## Blockers
[Anything that stopped progress — next session's first task is resolving these]
- 🚫 [Blocker]: [what's needed to unblock]

## Next Session Opening
[Exact first action for the next session — specific enough that a fresh agent can start immediately]
"Start by: [specific action]. Context loaded from this file."

## Skills in Use
[Which Super Skills are active for this task — next session inherits these]
- [skill]: [why it's relevant to remaining work]