Session handoff

Session Handoff

Generate a structured handoff document at outputs/HANDOFF.md at the end of a work session. Goal: the next session (or another developer) can pick up exactly where this one left off without reconstructing context from scratch.

Language: the handoff content follows the language of the user's request (English request → English handoff, German request → German handoff). Commit messages and code stay in their original language.

Output path: always outputs/HANDOFF.md (consistent with branch-review / full-project-review). outputs/ should be .gitignore-d at repo level; that is the repo's responsibility, not this skill's.

Examples

# Simple handoff without arguments
/session-handoff

# With an optional focus hint
/session-handoff Focus: Auth refactoring and new API endpoints

# With a time hint (overrides the default heuristic)
/session-handoff since Monday

Step 1: Determine the session boundary

The session boundary decides which commits land in the handoff. Resolution order:

1. Conversation context first. You know from this conversation when the session started — use that knowledge primarily. Example: "we started with the auth refactor today" → only commits from the first refactor commit onward.
2. $ARGUMENTS time hint (if present): "since Monday", "last 2 days", "today" → translate into --since="...".
3. Fallback heuristic (only if 1 and 2 yield nothing): take the last 20 commits and mark in the handoff explicitly that the session boundary is uncertain.

Do not rely on @{N hours ago} — that reflog syntax is empty on fresh clones and silently produces empty diffs.

Step 2: Collect data

# Date/time with timezone → fills {DATE_UTC}
date -u '+%Y-%m-%d %H:%M UTC'

# Repo name → fills {REPO-NAME}
basename "$(git rev-parse --show-toplevel)"

# Current branch → fills {BRANCH}
git branch --show-current

For the commit range, use the boundary determined in Step 1. Examples:

# Variant A: conversation context says "since commit <SHA>"
git log --oneline <SHA>..HEAD

# Variant B: $ARGUMENTS has a time hint (translated to --since)
git log --oneline --since="<translated time hint>"

# Variant C: fallback (session boundary uncertain)
git log --oneline -20

Changed files for the same range: git log --name-only --pretty=format: <range> | sort -u.

# Currently uncommitted changes
git status --short

# Open TODOs in code (common patterns, includes untracked files)
git grep --untracked -n "TODO\|FIXME\|HACK\|XXX\|NOCOMMIT" -- ':!*.lock' ':!node_modules' 2>/dev/null | head -40

Optionally read files the git data identifies as central (e.g. files with the largest churn in the range, CLAUDE.md if present).

Step 3: Write HANDOFF.md

Ensure the output directory exists:

mkdir -p outputs

Check for an existing file:

• If outputs/HANDOFF.md exists → default: prepend a new dated section at the top (old sections stay intact).
• Only ask the user when they signal a different strategy ("replace", "rewrite").

Generate the file contents using the schema below. Important: the HTML comments (<!-- ... -->) are instructions for you — they must not appear in the final file. Replace each comment with the actual content, or leave the section as _(none)_.

Section headers in the template are shown in English; translate them to the user's request language when emitting the file.

# Session Handoff — {DATE_UTC}

> Generated by `/session-handoff` · Repo: {REPO-NAME} · Branch: {BRANCH}

---

## What was implemented

<!-- List of concrete changes in this session, grouped by feature/area.
     Each point should make clear: what? where (file/module)? -->

- ...

## Commits in this session

<!-- The relevant git commits as a compact list -->

| Hash | Message |
| ---- | ------- |
| ...  | ...     |

## Uncommitted changes (WIP)

<!-- Auto-filled from `git status --short` — shows what is not yet committed.
     If nothing is uncommitted: write `_(none)_`. -->

- ...

## Key decisions

<!-- Architecture or design decisions that were made — and WHY.
     Important: also briefly name rejected alternatives so the next
     session does not retrace the same dead ends. -->

- **Decision:** ... **Rationale:** ...

## Open questions

<!-- What is unresolved? What still needs discussion, research, or a decision?
     Phrase concretely and actionably. -->

- [ ] ...

## Open TODOs in code

<!-- Auto-filled from `git grep TODO/FIXME` — only relevant ones, no stale entries -->

- [ ] `file.ts:42` — ...

## Recommended next steps

<!-- Prioritized tasks for the next session. Top priority first.
     Each step should be immediately actionable (no vague "continue"). -->

- [ ] ...
- [ ] ...
- [ ] ...

---

_Last updated: {DATE_UTC}_

Notes on filling the schema

What was implemented: derive from the git commits and changed files. Summarize what logically belongs together — do not list every commit individually, group by feature/area.

Decisions: also write down what was not implemented and why. That information is often more valuable than the description of what was done.

Uncommitted changes: fill the section with git status --short. If nothing is uncommitted, write _(none)_.

Open TODOs: filter the git grep output — keep only TODOs that arose in this session or that matter for the next steps. Drop old TODOs in untouched files.

Next steps: be concrete. Instead of "write tests", write "add unit tests for AuthService.login() in tests/auth.test.ts".

Optional arguments ($ARGUMENTS): if the user passed focus topics, notes, or a time hint, factor them into Step 1 (session boundary) and into prioritizing the next steps.

Step 4: Confirmation

Tell the user:

• Path of the created/updated file (outputs/HANDOFF.md)
• Short summary: how many commits, how many open questions, how many next steps
• Whether a new section was prepended or the file was newly created

Related skills

• agent-context-update — when project-spanning knowledge from this session should flow into the Agent-Context alongside the handoff.
• branch-review — when a code review of the session changes is wanted before the handoff.