session-handoff

Session Handoff

Create handoff documents that enable seamless context transfer between sessions.

Critical Requirements

Line Endings

Use LF (Unix) line endings only. Never CRLF.

• Use the Write tool directly (handles line endings correctly)
• Never copy-paste from Windows clipboard
• If you see ^M characters, rewrite the file

File Naming

Pattern: sessions/session_{N}_{YYYYMMDD}.md

• {N}: Session number (integer, no leading zeros)
• {YYYYMMDD}: Date without separators

Examples: session_5_20260104.md (correct), session_05_20260104.md (wrong)

Handoff Template

# Session {N} Handoff

```yaml
session: {N}
date: {YYYY-MM-DD}
phase: "P{X} - {Phase Name}"
task: "P{X}.{Y} - {Task Name}"
status: {completed | in_progress | blocked}
tokens_end: "~{X}K ({Y}%)"
```

---

## Session Summary

{2-3 sentences on outcomes, not process. What was achieved?}

## What Was Accomplished

- [x] {Completed item with file path}
- [x] {Completed item with file path}
- [ ] {Incomplete item - carried forward}

## Files Created/Modified

| File | Action | Lines | Purpose |
|------|--------|-------|---------|
| {path} | Created | ~{N} | {Brief description} |
| {path} | Modified | +{N}/-{M} | {What changed} |

## Verification Status

| Check | Status | Notes |
|-------|--------|-------|
| Typecheck | {Pass/Fail/Skipped} | |
| Lint | {Pass/Fail/Skipped} | |
| Tests | {Pass/Fail/Skipped} | {X/Y if applicable} |

## Technical Decisions

### {Decision Title}
- **Decision**: {What was decided}
- **Rationale**: {Why}
- **Impact**: {What it affects}

## What's Next

1. {Specific actionable step}
2. {Next step}

## Blockers / Issues

{List blockers or "None"}

## Learnings

{Patterns discovered or "None"}

Section Guidelines

YAML Header (Required)

The YAML header enables metrics collection. All fields required:

Field	Format	Example
session	Integer	session: 5
date	YYYY-MM-DD	date: 2026-01-04
phase	Quoted string	phase: "P1 - Foundation"
task	Quoted string	task: "P1.2 - Test Auditor"
status	Enum	status: completed
tokens_end	Quoted string	tokens_end: "~95K (48%)"