session-handoff

name	session-handoff
description	Write a per-topic handoff file and log it in a single index at the end of a working session, so any topic can be resumed later in a fresh session. Use when the user wants to wrap up or park a session ("handoff", "wrap up", "park this"), or to resume or pick up a previous topic. Also suggest it proactively when a substantive session is clearly winding down.

Session Handoff

Preserve session context per topic. Each topic gets one handoff file holding its current resumption state (not a diary). A single index is the log and the menu of what can be picked up.

Layout

handoffs/
├── INDEX.md            # active-topics table + reverse-chron session log
├── <topic-slug>.md     # one file per topic, rewritten each session end
└── archive/            # completed topics

handoffs/ lives at the project root (the git root, or wherever the project's CLAUDE.md sits). If the root is genuinely ambiguous, ask once and record the chosen location in INDEX.md so future sessions don't re-ask.

If handoffs/ doesn't exist, create it (and INDEX.md from the format below).

Ending a session

1. Gate. If the session produced nothing novel, actionable, or durable (quick lookups, trivial edits), say so and stop. No empty handoffs.

2. Resolve the topic. Read INDEX.md. Match this session to an existing topic or mint a new kebab-case slug (specific: zaru-order-book, not liquidity). If a session genuinely spans two topics, write two handoffs. If the match is ambiguous, ask.

3. Rewrite the handoff file from scratch using the template below. It must let a fresh session (or a colleague) resume with zero other context. Keep it under ~60 lines. Reference artifacts by path/URL — never duplicate their content. Apply the gate per item.

4. Prepend one line to the session log in INDEX.md and update the active-topics table (status + date).

5. Flag promotions — don't apply them. If a durable learning belongs in a skill, CLAUDE.md, or other shared infrastructure, list it under "Suggested promotions" in the handoff and tell the user. Never edit shared files yourself.

6. Confirm. Report: topic, file path, one-line status, any promotions flagged.

Handoff file template

# <Topic title>

**Status:** <one sentence — where this stands right now>
**Updated:** YYYY-MM-DD

## Goal
<Why this topic exists, 1–2 sentences.>

## Current state
<What's done and what's true now. Bullets.>

## Decisions
<Decisions made and why, so they aren't relitigated.>

## Open threads
<Unresolved questions, risks, things being waited on.>

## Next steps
<Concrete first actions for the next session, most important first.>

## Artifacts
<Paths / URLs / doc links. Pointers only.>

## Suggested promotions
<Optional: learnings that belong in shared infrastructure, for human review.>

INDEX.md format

# Handoffs

## Active topics
| Topic | Status | Updated |
|---|---|---|
| [zaru-order-book](zaru-order-book.md) | Awaiting risk review | 2026-07-02 |

## Session log
- 2026-07-02 — [zaru-order-book](zaru-order-book.md) — drafted unified book proposal; open: custody question

New log entries go at the top. One line per topic per session end.

Resuming

When asked to resume ("pick up X", "where were we on X", "what's open"):

• Named topic → read its handoff file, confirm the next steps, continue.
• No topic named → show the active-topics table and ask which one.
• Only read the artifacts the task at hand requires, not everything listed.

Completing a topic

When the user says a topic is done: move its file to handoffs/archive/, append a ✅ Done line to the session log, and remove it from the active table.