Close New Session

/close-new-session — close + handoff

Two deliverables: long-term memory (what matters in months) and the handoff (what matters in five minutes, in the new session). They are different things. Do not merge them.

• Memory = durable facts, no session noise.
• Handoff = volatile state: what was half-edited, what command was running, what was tried and failed.

Step 1 — Real state

git status --short
git diff --stat
git log --oneline -8
git stash list
ls -t docs/handoffs/*.md 2>/dev/null | head -3

If docs/handoffs/ does not exist, create it. If the repo has no docs/, use .claude/handoffs/.

Step 2 — Chain

Look at the most recent handoff listed. If it covers the same thread of work, this is its continuation: inherit the slug and bump the sequence number. If it is a new topic, start at 01.

Name: docs/handoffs/YYYY-MM-DD-<slug>-<NN>.md Example: docs/handoffs/2026-08-25-auth-rewrite-03.md

Step 3 — Memory

Follow memory-triage.md (same skill folder). Read it before writing. Same filter as /close: only what cannot be deduced from the repo. Look for duplicates. Update MEMORY.md.

Do this before the handoff, so the handoff can point at memories by slug instead of repeating them.

Step 4 — Write the handoff

Full template. Fill every section; if one is empty, write "—" rather than deleting it.

# Handoff — <title of the thread of work>

**Date:** YYYY-MM-DD · **Sequence:** NN · **Previous:** <previous file or "—">
**Branch:** <branch> · **Last commit:** <short sha> <subject>

## Goal
<One sentence: what this thread is trying to achieve. Not today's work — the whole thread.>

## Where we are
<10-20 bullets. Concrete state, not narrative. What works, what doesn't, what is half-built.>

## What was tried and did NOT work
<The most valuable section. Each attempt with why it failed, so nobody repeats it.>
- <approach> → failed because <reason>

## Decisions taken
- <decision> — because <reason> — <date>

## Files touched
<Relative paths + one line on what changed in each. Mark the uncommitted ones.>

## Uncommitted
<Output of git status --short, or "clean">

## Context that is not in the repo
<IDs, URLs, credentials by location (NEVER the value), which VPN is needed, what is down.>

## Memories written in this close
- [[memory_slug]] — <what it covers>

## Next step
1. <concrete action>
2. <concrete action>
3. <concrete action>

## Quick start
```bash
<exact commands to restore the environment: cd, VPN, server, tests>
```

Content rules:

• Exact paths and commands. "the config file" is useless; src/config/database.ts is not.
• Never a token or secret value. Only where it lives.
• Absolute dates.
• If something was not verified, write it as unverified. A handoff that lies costs more than an empty one.

Step 5 — Return the resume prompt

End with this, in a code block so it can be copied in one go:

## Session closed — handoff ready

Memory:
  + <file>.md — new: <hook>
  ~ <file>.md — updated: <what changed>

Handoff: docs/handoffs/<file>.md  (sequence NN)

**Paste this into the new session:**

```
Read docs/handoffs/<file>.md and continue from "Next step".
```

What NOT to do

• Do not commit or push unless explicitly asked. The handoff is written to disk (that is the point), but it stays uncommitted unless the user says otherwise.
• Do not duplicate in the handoff what already went into memory — link it by slug.
• Do not write a generic handoff. If you cannot name the concrete next step, the handoff is worthless.