claude-skills/.wiki/concepts/session-handoff-skill-design.md

---
title: session-handoff skill — design rationale
type: concept
updated: 2026-05-25
---

# session-handoff — design rationale

Why the skill exists in this shape, with the trade-offs that were considered and the decisions that closed them. Source buffer: `~/projects/.workshop/.archive/2026-05-24-session-handoff-skill.md` (Round 1 brainstorm + Round 2 Q1–Q10 resolution).

## The problem

Every fresh CC session in a project starts cold. The agent re-reads `STATUS.md`, greps recent buffers, looks at `MEMORY.md`, and asks the user "where were we?". That's a recurring fog — the user already told the previous session what to do next, and the previous session may have already formulated the plan, but the bridge between sessions doesn't exist.

The fix: the agent **writes a forward-looking handoff prompt** at session boundaries, into a canonical location the next session reads on cold start. Sliding overwrite: one file, one current state, history through `git log -p`.

## Why a new skill, not an extension

The shape was tempting to fold into `using-tasks` — it already touches `.tasks/`. But the lifecycles don't match:

- `using-tasks` is **per-task** (switch, start, pause, close).
- `session-handoff` is **per-session** (start-cold, end-warm).

Different triggers, different readers, different writers. Per-task state and per-session state happen to share a directory but they answer different questions.

## Architecture

**Location:** `.tasks/NEXT_SESSION.md`. Sits next to `STATUS.md` so the `using-tasks` reader already walks `.tasks/` on cold start and notices the handoff without an extra hook.

**Sliding overwrite:** every write fully replaces the file. No `.archive/handoff-<date>.md` fanout — `git log -p .tasks/NEXT_SESSION.md` is the history if anyone needs it. Rejected the append-with-archive variant because it produces N artefacts the user didn't ask for; the git-log path covers the same need on demand.

**Project scope:** no global state. Workshop and `.admin/` sessions don't see each other. "Wrap up session" in one tree does not touch the other.

**Modes:** read on session start (orient + ask, never auto-execute); write on session-end phrase or on substantive commit.

## Triggers — the resolved choices

### Read-mode (session start)

Activated by the `CLAUDE.md` trigger line `session handoff: read on start, write on end` (canonical, added to `project-bootstrap` v1.12.0 template). On cold start: if `.tasks/NEXT_SESSION.md` exists and is fresh, summarise + ask user before any action. If `_last_updated_` is older than 7 days, flag staleness explicitly: "handoff от <date> (N days ago) — overwrite or continue?".

Default is **orient + ask**, never auto-execute. The previous session might have been wrong; user agency survives.

### Write-mode — phrase whitelist

Strict whitelist (rejects close-but-different phrases):

- Russian: «завершаем сессию», «сворачиваемся», «закругляемся»
- English: «wrap up session», «end session», «we're done for now»

Explicit anti-patterns that **must not** trigger:

- «закрываем эту таску» — task close, lives in `using-tasks` zone
- «pause», «приостанови» — task-pause, not session-end
- «отбой», «разбегаемся» — too broad; may refer to a different context
- «сейчас завершу одну задачу и тогда поговорим» — partial completion

On ambiguity (e.g. «закругляемся» with a task-marker tail), the skill **asks** "session or task?" rather than guessing. Closing-bias is the failure mode to avoid.

### Write-mode — substantive-commit heuristic

```
prefix NOT IN (meta:|docs:|style:|chore:|fix typo)
AND (body_length > 200 chars OR files_changed > 3)
```

Plus an explicit "first non-trivial commit of the session always triggers" exception. The reasoning: the *start* of work is itself a context shift worth recording, even when the first commit is small (bootstrap, scaffolding).

The thresholds are tuned to skip the noise (`chore: bump dep`, `docs: typo`) while catching the actual session-shaping commits. They're not magic numbers — they're the floor below which a handoff regen would dominate signal with noise.

## Optional PostToolUse hook

A behavioral memory ("after `git commit`, check the substantive heuristic") is fragile — one missed check leaves the next session with a stale handoff. Solution: an opt-in PostToolUse hook (`skills/session-handoff/hooks/commit-detector.{ps1,sh}`) that emits a `hookSpecificOutput.additionalContext` system reminder after every substantive commit. Harness-side determinism replaces the agent-side memory.

**Why opt-in, not auto-installed:** `install.sh` deliberately does not mutate `~/.claude/settings.json`. Auto-rewriting the user's hook config on every skill install is the wrong shape — user expects `install.sh` to copy files, nothing more. Hook is shipped as scripts; user enables once per machine via the snippet in `hooks/README.md`.

**Known caveats:**
- Rebase / cherry-pick noise: every commit in a batch re-fires the hook. Deferred — opt-in bounds the cost.
- Hook can't see session boundaries, so it under-detects small first-commits-of-session that the agent-side heuristic does catch. Acceptable trade-off for harness-side determinism.
- Hook only **signals**; never auto-invokes write-mode. The agent still decides — preserves the user-agency invariant.

## Handoff content contract

Five required sections. Empty sections keep their heading + `(нет на этом раунде)` note so the next agent sees "nothing to do here", not "missing":

```markdown
---
_last_updated_: <ISO date>
session_id: <hash or date>
---

# Next session handoff

## Recent commits
- <slug>: <subject>   (3–5 most recent)

## Open треки
| Трек | Готовность | Entry-point |
|---|---|---|

## Спроси user'а
- <pending decision>

## Не делать (preemptive guards)
- <guard>

## Memory updates за сессию
- <what was saved / updated>
```

Handoff is **forward-looking** — a bridge of new things specific to the next turn, not an overview of the whole project. `STATUS.md`, `MEMORY.md`, and `.wiki/log.md` remain authoritative for their respective scopes. Don't duplicate them; reference them.

## Mid-task capture

If a 🔴 active task exists in `STATUS.md` at write time, the handoff captures `left mid-task: <slug> / where_stopped: <text>`. Rationale: friction of refusing the user ("can't wrap up, you have active work") is worse than the cost of capturing the mid-task state for the next session to resume. User agency owns the call, not the skill.

## Failure modes that exit early

- `CLAUDE.md` missing the trigger line → silent exit (opt-in per project).
- Not in a git work-tree → silent exit.
- `.tasks/NEXT_SESSION.md` absent in read-mode → silent exit (first session of project).
- Content matches secret patterns (`AKIA…`, `sk-…`, `ghp_…`, `BEGIN PRIVATE KEY`, `password=…`, etc.) → **abort write**, surface to user. File goes to git, no credentials.
- Stale handoff (>7 days) in read mode → **ask** rather than silent — overwrite-or-continue is a user call.

## What the skill explicitly doesn't do

- Auto-execute action items from a read handoff. Default is orient + ask.
- Append-with-archive. Sliding only.
- Trigger on `chore:` / `docs:` / `meta:` commits, on broad farewells, or on partial-completion phrases.
- Touch other projects. Per-project scope, full stop.
- Depend on a harness `SessionEnd` hook — Claude Code doesn't have one. The available hooks are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification`. The substantive-commit detection rides on `PostToolUse`.

## Precedent comparison

| Source | Lifecycle | Why it doesn't cover the handoff case |
|---|---|---|
| `using-tasks` STATUS.md `where_stopped` / `next_action` | per-task | misses per-session orientation; handoff needs to bridge tracks, not lock onto one task |
| `_queue.md` | parked topics | passive park, not active handoff |
| `MEMORY.md` | long-term facts | not anchored to a session boundary |
| `.wiki/log.md` | append-only chronology | timeline, not active orientation |
| Karpathy daily logbook | personal diary | points to the past (what happened); handoff points to the future (what to do next) |

Handoff is forward-looking; everything else is backward-looking or timeline-agnostic. That's the slot the skill fills.

## Acceptance — how the cluster closed

The skill shipped 2026-05-24 at v0.1.0, with PowerShell hook bug-fix at v0.3.1. Closure cluster — 7/7 tasks:

1. `[session-handoff-install]` — install.sh + reload + smoke.
2. `[session-handoff-hermes-mapping]` — `pending` mode in `hermes/mapping.yaml`.
3. `[session-handoff-bootstrap-template-extend]` — `project-bootstrap` v1.12.0 template gets the trigger line out of the box.
4. `[session-handoff-posttooluse-hook]` — `hooks/` shipped, opt-in snippet documented, stdin smoke verified.
5. `[session-handoff-existing-projects-upgrade]` — manual edit-pass on this machine; 4 repos deferred per-machine.
6. `[session-handoff-test-trigger]` — 15/15 behavioral outcomes match (6 whitelist + 4 antipatterns + ambiguity ASK + read-mode R1/R2 + hook H1/H2/H3).
7. `[session-handoff-review]` — 6/6 review dimensions ✓ via test-trigger smoke, 0 findings filed, skill v0.3.1 ships unchanged.

The smoke validated the load-bearing design decisions: ambiguity resolution by asking, the always-first-commit exception, default orient + ask in read-mode. None of them surfaced as gaps — every test came back as a confirmation of the resolved design.

## Related

- `pulling-before-work` — the precedent for a `CLAUDE.md`-triggered skill that runs once per session at a defined boundary.
- `project-bootstrap` v1.12.0+ — adds the canonical trigger line to new projects.
- `using-tasks` — owns `STATUS.md` and `<slug>.md`; the handoff explicitly does not replicate them.