handoff

handoff

End-of-session ceremony. The symmetric counterpart to prime, which loads what this skill writes.

The ordering is load-bearing: articulating "what's next" first surfaces forgotten todos AND structural conventions that should land in CLAUDE.md before we lose them.

Pre-rendered context

Branch: !git branch --show-current

Status: !git status --short

Recent commits: !git log --oneline -5

Graphite stack: !st status 2>/dev/null || echo "(st not available or no stack)"

Instructions

Run sequentially — each step's output informs the next.

1. Articulate what's next (forces reflection)

Before writing anything, state in chat:

• What was the last meaningful action this session?
• What is the next intended action (specific — not "continue work")?
• What obstacles or open questions are blocking the next action?

Doing this first surfaces things you'd otherwise drop: incomplete todos, missing tracker entries, conventions that should land in CLAUDE.md.

2. Write .ai-docs/handoff.md

Terse — 5-10 lines. The cold-start /prime skill loads this verbatim into the next session.

Format:

# Handoff — <YYYY-MM-DD>

**Branch:** `<branch>`
**Last action:** <one-line description of last meaningful change>
**Next action:** <specific next step — file path or command, not "continue X">
**Obstacles:** <bulleted, or "none">

## Notes
<optional: anything the next session needs that doesn't fit above>

Overwrite the existing handoff.md if present. Previous version is in git history.

3. Update memory

Memory lives at ~/.claude/projects/-Users-USER-Projects-PROJECT/memory/.

For this session, write any of these that apply (skip what doesn't):

• feedback memory: corrections or validated approaches the user expressed (with **Why:** and **How to apply:** lines per global memory protocol).
• project memory: ongoing-work facts not derivable from code or git (deadlines, ownership, motivation).
• user memory: stable role/preference facts about the user.
• reference memory: pointers to external systems referenced this session.

Don't save: code patterns, fix recipes, ephemeral state, anything in CLAUDE.md, anything in commit messages. Index each new file in MEMORY.md with a one-line hook.

4. Update tracker (if applicable)

For each completed work item:

• Close the tracker issue or post a closing comment.
• Update state:* labels per .claude/primitives/task-management/<value>.md.

For each parked / discovered work item:

• File a new tracker issue with enough context to pick up cold.

If no tracker writes are needed (e.g. a meta-session that didn't touch issues), skip explicitly.

5. Update CLAUDE.md if structural decisions landed

Edit CLAUDE.md only if the session introduced a convention, layout rule, or tool that future sessions need to know and that isn't documented elsewhere. Examples:

• New top-level directory under .claude/ or .ai-docs/.
• New skill that future sessions should auto-trigger.
• New primitive category.
• Convention change (file naming, branch shape, etc.).

Don't duplicate content that lives in skills, primitives, or RFCs — link to them from CLAUDE.md instead.

6. Verify clean working tree

Run:

git status
st status 2>/dev/null || true

For each uncommitted file:

• If part of completed work and the user wants to commit → propose a commit message and ask before running.
• If WIP → stash with a descriptive note, OR leave uncommitted if handoff.md references it explicitly.
• If accidental → ask the user.

Never auto-commit, auto-stash, or auto-discard. Surface the state and let the user decide.

7. Summary + confirmation

Print a single block summarizing:

• What landed (memory entries, handoff.md path, CLAUDE.md edits if any, tracker updates if any).
• What remains uncommitted.
• The line /prime will surface next session as the opening move.

Wait for the user to confirm before they clear context.

Constraints

• Read-only on git history. Never git reset, git rebase, force-push, or amend during handoff.
• Never auto-commit. The user owns commit decisions.
• Don't write speculative memory entries. If nothing new and durable was learned this session, write none.
• The handoff is for the next session of this project, not a generic AI. Reference paths, branch names, and tracker keys directly — assume the reader is starting cold but in this repo.
• Articulate-first ordering is non-negotiable. Skipping straight to file writes loses the reflection that surfaces missing items.