Session Closeout

A clean closeout produces two things, and they are not the same:

• Durable memory — STATE.md, tasks/lessons.md, CLAUDE.md. These are read at the start of every future session. They answer "what is permanently true about this project now?"
• The bridge — a dated handoff file written for exactly one session: the next one. It answers "what just happened, and what's the next move?"

Do the durable memory first, then the bridge — that way the handoff can point at what you just recorded instead of duplicating it. The audience for all of it is a future instance of you, not a stakeholder: this is context engineering, not a status report.

When to invoke

The user says "wrap up session", "session closeout", "close out", "end of session", "we're done for today", "let's wrap up", "session handoff", "hand off", "handoff summary", "summarize before I clear", or any near-equivalent. Also invoke proactively whenever the session is ending — the user is about to /clear, /compact, or stop for the day.

If the user clearly wants only a quick handoff to carry elsewhere (e.g. to paste into a parallel agent) and not a full wrap-up, you can run just the bridge (Step 2) and skip the durable-memory reconcile. But the default for "end of session" is both — stale STATE.md/lessons.md is the usual reason continuity breaks across sessions.

First, gather what happened this session

Both outputs draw on the same source material, so collect it once:

1. Review the full conversation, not just the last few turns. Closeouts miss things when they only summarize recent context.
2. Pull from these sources (in order):
   • Plan files referenced this session (check ~/.claude/plans/ if a plan was mentioned).
   • TodoWrite state — any in-progress or pending tasks.
   • Background processes you started with run_in_background — shell IDs are load-bearing for the next agent.
   • Files created or modified this session — you know what you touched; don't grep to re-discover.
   • Memory files written or updated (~/.claude/projects/<project>/memory/).
   • Unresolved questions — things you asked the user that never got a clear answer, or things the user asked that got deflected.
3. Do NOT audit the filesystem. This is synthesis of what happened in THIS session — no git log, no broad Glob sweeps. If you didn't touch it this session, it doesn't belong here.

Then route it: infrastructure/URL/deploy changes → STATE.md; corrections and gotchas → lessons.md; new constraints, key files, or workflow rules → CLAUDE.md; everything the next session needs to continue → the bridge.

Step 1 — Reconcile the durable memory

Ensure these three files exist and reflect reality. Create any that are missing; update the ones that already exist. Default locations: STATE.md and CLAUDE.md at the project root, lessons.md under tasks/. If the project already places them elsewhere, follow that.

Change only what this session actually changed — these files are read at the start of every session, so noise costs every future agent. Don't fabricate a lesson when nothing went wrong, and don't rewrite sections you didn't touch.

STATE.md — living source of truth

The current snapshot of the project: live URLs, infrastructure status, secrets location (never the secret value), contacts, branching model, and a session log. Every session, bump the Last updated line and add one newest-first row to the session log; touch the other sections only when infra actually changed. Include only the sections that apply.

# <Project> — Project State

> Last updated: YYYY-MM-DD | Updated by: Claude

## Current Status: <one-line statement of where the project stands>

## Live URLs
| URL | Purpose | Auth |
|---|---|---|

## Infrastructure
| Component | Status | Details |
|---|---|---|

## Secrets & Credentials      ← location only, never the value
| Secret | Location | Notes |
|---|---|---|

## Branching & Deployment
<branch model + deploy notes>

## Session Log                ← newest first, one row per session
| Date | Summary |
|---|---|
| YYYY-MM-DD | <what this session shipped, in one line> |

tasks/lessons.md — mistake log

Append a lesson whenever the user corrected you this session, or you hit a non-obvious gotcha worth preventing next time. Group by session, number continuously across the file, and tag each with a [Category] (e.g. [Workflow], [Git], [Data], [RTL]). State the problem and the rule that prevents a repeat — the rule is the payload, not the story. If a lesson generalizes beyond this project, mark it [PROMOTED → reference_X.md] so it can be lifted into global memory later. No corrections this session → add nothing.

# Lessons Learned

## Session: YYYY-MM-DD — <topic>

### <N>. [Category] <short title>
**Problem:** <what went wrong, concretely>
**Rule:** <what to do instead, so it never recurs>

CLAUDE.md — project context

Only ever the project's CLAUDE.md at the repo root — never the global ~/.claude/CLAUDE.md, which holds the user's personal cross-project instructions. Closeout reconciles project memory; it must never touch global config.

Project-specific overrides only — constraints, key file paths, workflow deviations. Keep it lean (~15-20 lines) and never duplicate global or default-workflow instructions that apply everywhere; this file is for what's true only in this project. Update it only when a constraint, key file, or workflow rule actually changed this session — otherwise leave it alone.

# <Project> — Project Context

## Constraints
- <hard boundaries: off-limits dirs, isolation rules, things never to do here>

## Workflow Overrides
- <where this project deviates from the default workflow>

## Key Files
| File | Purpose |
|------|---------|
| `STATE.md` | Live infra state, URLs, secrets location |
| `tasks/lessons.md` | Mistake log — review at session start |

If the project keeps other living docs current — architecture, data model, a QA index, a README with counts — update those too when this session changed them. Same rule: only what changed.

Step 2 — Write the handoff bridge

Write the handoff to a file, then echo it in chat. The file is the point: after /clear the conversation is gone, and a fresh agent cannot read a chat that no longer exists — but it can Read a file. Echoing it in chat lets the user eyeball it before they clear.

Where to write it — pick a durable, predictable path and state the path you chose:

• Prefer tasks/session-YYYY-MM-DD-handoff.md if a tasks/ directory exists (the common convention).
• Otherwise write session-YYYY-MM-DD-handoff.md in the current working directory.
• If the user names a location, use theirs.

Use the actual date in the filename. If a handoff for today already exists, append a counter (-2) rather than overwriting — the earlier one may still be needed.

Output template — use exactly this structure, every time

# Session Handoff — <one-line title of what this session was about>

## Where it started
<2-3 sentences: what the user asked for, key framing or constraints that emerged>

## Decisions locked + what shipped
- <decision or change> — <why, and where it lives (absolute path if a file)>
- ...

## Key files for next session
- `<absolute path>` — <why the next agent should read this first>
- Plan file: `<path>` (if a plan drove the session)
- Memory files touched: `<paths>` (if any)

## Running state
- Background processes: <shell IDs + what they are + how to stop them> — or "none"
- Dev servers / ports: <url + port> — or "none"
- Open worktrees / branches: <paths> — or "none"

## Verification — how to confirm things still work
- `<command>` — <expected outcome>
- ...

## Deferred + open questions
- Deferred: <item> — <why pushed to later>
- Open: <question needing the user's input> — <context>

## Pick up here
<1-2 sentences: the single most likely next action for a fresh agent>

Step 3 — Report back and tell the user how to resume

In one message, give the user the closeout receipt: which durable files you created or updated (and what changed in each), where the handoff was written, and the single line that bootstraps the next session. The artifact is useless if the human doesn't know how to feed it to the next agent. For example:

Updated STATE.md (status + session log) and added lessons 58–59 to tasks/lessons.md; no CLAUDE.md change needed. Handoff at tasks/session-2026-06-01-handoff.md — after /clear, start the next session with: Read tasks/session-2026-06-01-handoff.md and continue.

This closes the loop. Without the resume line, the user clears the context and is left holding a file the next agent was never told to open.

Hard rules

Each exists for a reason — the reason is what makes the closeout trustworthy, not the rule itself.

Durable memory

1. Change only what changed. These files are read at the start of every session, so a fabricated lesson or a needlessly rewritten section misleads every future agent. Always add a session-log row and bump STATE's date; touch every other line only when this session genuinely changed it.
2. Secrets: location only, never the value. STATE records where a secret lives (vault, env var, dashboard) — committing the secret itself is a leak.
3. Lessons from real corrections only; CLAUDE.md stays lean and project-scoped. A lesson is worth recording only when something actually went wrong or surprised you. Only ever touch the project's CLAUDE.md at the repo root — never the global ~/.claude/CLAUDE.md. It holds project-specific overrides only; duplicating global workflow there creates two sources of truth that drift apart.

The bridge

4. Write to a file, then echo in chat. Chat alone is wiped by /clear, and a fresh agent can't read a conversation that no longer exists. The file is the only thing that survives the reset.
5. Never invent state; absolute paths always; plan file first. If a section has nothing, write "none" — don't omit it (a missing section reads as "forgot to check"). Use absolute paths, since the next agent may have a different working directory. If a plan drove the session, list it first in "Key files".
6. Background-process shell IDs are load-bearing. List every run_in_background shell in "Running state" with how to stop it (the exact command depends on the next agent's OS) — otherwise the next agent has to rediscover them.

Both

7. Terse and concrete; synthesize this session, nothing more. Paths, commands, shell IDs, decisions — the tone of a seasoned engineer handing off at end-of-shift. No emojis, no hype, no "what went well / what went poorly" retro. Don't pad the handoff out of the last three turns, and don't recommend next steps beyond the single "Pick up here" line — the next agent decides what to do.