# Context Handoff Closeout

A small handoff template for Claude Code / coding agents when you are about to switch context, clear the session, or hand work to another agent.

## The rule

Do not use `/compact` as the default handoff.

- Use `/compact` when you are staying on the same task and the current conversation is too heavy.
- Use `/clear` plus a written closeout when you are switching tasks, changing agents, or starting fresh tomorrow.

The context window is not a filing cabinet. Write the handoff into the repo.

## Ask the agent to write this file

Copy/paste:

```text
Before we stop, write a concise handoff to docs/session-closeout.md.

Include only:
1. Current goal
2. Decisions made
3. Files changed
4. Commands/tests run and real results
5. Open risks or unknowns
6. Next 1-3 actions
7. Anything the next session must read first

Do not dump the transcript. Do not include stale plans. If a detail will not change the next session's decision, leave it out.
```

## Template

```md
# Session closeout — YYYY-MM-DD HH:MM UTC

## Current goal
-

## Decisions made
-

## Files changed
-

## Verification run
-

## Open risks / unknowns
-

## Next actions
1.
2.
3.

## Read first next session
-
```

## What goes where

| Information | Put it here | Why |
|---|---|---|
| Rule the agent should obey every run | `CLAUDE.md` | Stable instruction |
| What happened this session | `docs/session-closeout.md` or dated log | Next-session continuity |
| Decision that will matter in a month | `docs/decisions.md` | Durable project memory |
| Raw transcript | Nowhere by default | Too much stale context |
| Command output / receipt | Log or artifact link | Verifiable evidence |

## Pass / fail test

A closeout passes if the next session can answer:

1. What are we doing?
2. What must not be repeated?
3. What changed?
4. What was verified?
5. What is the next smallest safe action?

If it cannot answer those, your handoff is not memory. It is fog.