ashaykubal/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%)" |

Session Summary

Focus on outcomes not process. What was delivered?

Good: "Completed session-handoff skill with CRLF handling. Ready for use." Bad: "I started by reading files, then thought about structure, then wrote..."

What Was Accomplished

• Use [x] for complete, [ ] for incomplete
• Include file paths
• Be specific

Technical Decisions

Document decisions that affect future work. Include rationale so future sessions understand WHY. Skip if no significant decisions.

Blockers / Learnings

Always include these sections. Write "None" if empty - don't omit.

Quick Checklist

Before finalizing:

• [ ] File named session_{N}_{YYYYMMDD}.md
• [ ] YAML header complete and valid
• [ ] All sections present (even if "None")
• [ ] Next steps are specific and actionable
• [ ] No CRLF line endings

Examples

For detailed examples of completed and in-progress handoffs, see references/examples.md.