| name | handoff |
| version | 2.6.1 |
| description | Generate a structured handoff document for ending a development session. Saves to docs/sessions/ for the continue skill to read. |
| trigger | manual |
| depends-on | [] |
| references | [] |
| disable-model-invocation | true |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Bash, Edit, Write |
handoff
Skill metrics: Emit a start event to the activity log:
echo "{\"type\":\"skill\",\"event\":\"start\",\"skill\":\"handoff\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl
Generate a comprehensive handoff for ending a development session:
Phase 0: Validate Prerequisites
Before starting, verify:
docs/sessions/ directory exists (create if missing)- No conflicting session file for today's date
If the directory is missing, create it silently and proceed.
1. Capture Current State
Analyze:
- Current branch:
git branch --show-current
- Git status (uncommitted changes?)
- Open PRs:
gh pr list --author @me --state open
- Current sprint spec (if exists:
docs/sprints/sprint-*.md) — extract sprint goal, capacity used, and any decisions logged this session
- Last entries in @docs/progress.md
2. Document Progress
If work was done this session, ensure it's captured:
- Sprint spec updated with progress
- Any decisions documented
- Blockers noted
3. Generate Session File
Save a structured session file to docs/sessions/session-YYYY-MM-DD.md.
The file MUST start with YAML frontmatter for /resume searchability:
---
date: YYYY-MM-DD
sprint: [current sprint number]
sprint_goal: "[sprint goal — one sentence from sprint spec]"
sprint_capacity: "[sessions used/total — e.g., 5/8]"
branch: [branch-name]
stories: [comma-separated story IDs worked on]
status: [completed | in-progress | blocked]
---
# Session Handoff — [YYYY-MM-DD]
## Git State
- **Branch:** [branch-name]
- **Uncommitted changes:** [yes/no — list if yes]
- **PR Status:** [Open #123 / Merged / Not created]
## Work Completed
- [x] [Task/story completed]
[ ] [Task in progress — what's done, what remains]
[Decision]: [Rationale]
[Issue]: [Status]
[path/to/file]: [what changed and why]
[path/to/file]: [why this file was important to understand]
[path/to/file]: [explored but not relevant to current work]
Passing: [count]
Failing: [count]
Coverage: [percentage if available]
[The single next thing to do — be very specific]
[Second priority]
[Third priority]
@[path] — [why this file is needed]
<!-- Populated from activity log if available -->
[Any issues the next session should be aware of]
**Activity summary:** Parse the activity log to populate the "Activity Summary" section with: total edits, total commands run, most-edited files (top 5), and edit-to-bash ratio.
Offer to add a session summary as a PR comment. This helps teammates (and future-you) understand the reasoning behind the code — the minimum viable knowledge transfer (see `docs/reference/TEAM_WORKFLOW.md` → Session Summaries):
