session-handoff

name

session-handoff

description

Use when the user wants to start a fresh chat but keep the work going seamlessly. Triggers on "продолжим в новом чате", "упакуй контекст", "перенеси разговор", "save state for tomorrow", "подготовь промт для нового чата", "transfer to new session", "хэндофф", "суммаризируй чат", "summarize chat", "handoff", explicit /session-handoff, or any phrasing where the user signals they're ending the current chat but expects work to resume in another. Produces a handoff note + ready-to-paste first-message. Copies first-message to clipboard.

Session Handoff

Goal: give the next Claude session exactly what it needs to resume in under 30 seconds.

Step 0 — Detect mode

If session type is obvious from context — proceed directly. If ambiguous — ask ONE question:

"Это dev-проект с файлами/планом или research/brainstorm сессия без кода?"

---

MODE A: Dev project (has git / CLAUDE.md / plan files)

Goal: navigation pointer, not a report. Next Claude finds files, not reads a recap.

1. Collect state (inline, no subagents)

git log --oneline -5
git status --short | head -10

Use conversation context first — don't re-read files already seen.

2. Write handoff note

Hard limit: 55 lines. Cut, don't pad.

Path: docs/agents/SESSION_HANDOFF_<YYYY-MM-DD>.md

# Handoff — <Project> — <YYYY-MM-DD>

## Status
<one line: what's done, what remains>

## Read first (in order)
1. `<path/to/plan.md>` — tasks and plan
2. `<path/to/spec.md>` — spec (if relevant)
3. `CLAUDE.md` — project rules

## In-session decisions
<!-- Only decisions made in THIS chat not yet written to files. Omit section if empty. -->
- **<Decision>:** <reasoning> (rejected: <alternative> — <why rejected>)

## Next step
<one line: the specific task to start with>

## First message

``` ```

Never include: production state lists, full commit history, content that duplicates plan/spec.

3. First message rules

• Self-contained — next Claude has zero context
• Points to handoff doc and plan as source of truth
• Names the concrete first action
• Ends with "Жди мою команду"

Example:

Продолжаю <project>. Не начинай пока не скажу.

Прочитай:
1. `docs/agents/SESSION_HANDOFF_<date>.md`
2. `<plan.md>`

Затем запусти `<skill-name>` и жди команды.

4. Save and copy

git add docs/agents/SESSION_HANDOFF_<date>.md
git commit -m "docs: session handoff <date>"

cat <<'EOF' | pbcopy
<first message>
EOF

5. Report to user (≤4 lines)

• Path to handoff doc
• "Промт скопирован — Cmd+V в новой сессии"

---

MODE B: Research / brainstorm (no project files)

Goal: full context capture in one copy-paste block. Next Claude understands what was explored, decided, and why.

1. Silent reconnaissance

Gather from conversation (never ask user to explain again):

• Main objective and scope
• Key findings and insights
• Decisions made + reasoning
• Rejected alternatives + why
• Open questions
• User's work style / preferences visible in this chat

2. Auto-detect chat type

Pick the template variant:

• research — gathering info, analysis
• brainstorm — ideas, strategy, creative
• decision — evaluating options, choosing direction
• mixed — separate blocks per unrelated topic (rare)

3. Ask 1–3 clarifying questions only if real ambiguity

Skip if context is clear.

4. Write handoff note

Path: ~/Documents/HANDOFF_<YYYY-MM-DD>.md (no git project — save to Documents)

Deliver as a single fenced markdown block with one-sentence instruction above it:

# Handoff — <Topic> — <YYYY-MM-DD>
<!-- Chat type: research | brainstorm | decision | mixed -->

## TL;DR
<2-3 sentences: what this was about and where we landed>

## About
<context, constraints, starting point>

## Key findings
- <finding> — <source or basis>

## Decisions + reasoning
- **<Decision>:** <why> (rejected: <alternative> — <reason>)

## Open questions
- <question>

## Style notes
<!-- Only if user showed clear preferences: language, depth, format. Omit if no signal. -->
- <preference observed>

Rules:

• No empty sections — omit if nothing to put
• No chronological narrative — structured facts only
• No invented facts — cite from chat only
• Language matches user's recent messages
• No emoji, no preamble beyond the one-sentence instruction

5. First message

Продолжаю сессию по теме <topic>. Не начинай пока не скажу.

Прочитай: `~/Documents/HANDOFF_<date>.md`

Жди команды.

6. Copy to clipboard

cat <<'EOF' | pbcopy
<first message>
EOF

7. Report to user (≤4 lines)

• Path to handoff file
• "Промт скопирован — Cmd+V в новой сессии"

---

Anti-patterns (both modes)

• ❌ Duplicate plan/spec content in handoff doc (Mode A)
• ❌ Chronological narrative instead of structured facts (Mode B)
• ❌ Empty sections with placeholder text
• ❌ Invent facts not present in the conversation
• ❌ Handoff doc > 55 lines (Mode A) or with filler (Mode B)
• ❌ Re-read files already seen in this session
• ❌ First message that starts working immediately (must end with "Жди мою команду")