session-closeout

Session Closeout

A session that ends without closeout is work that has to be redone. Apply at the end of any multi-step project, before /reset, before stopping for the day, or before handing to someone else.

Procedure

The 6 surfaces

Reconcile each before declaring done. Tag with status: verified / pending / not-applicable.

Surface	Question	Evidence
Code	What did we actually change?	`git diff` + tests passing
Runtime	Does it actually work?	Live URL, deployed artifact, manual test
Docs	Can a new person understand what we built?	README, changelog, inline comments
Rules	Are the constraints the next session will see still correct?	CLAUDE.md / hooks
Memory	Is there anything the next session should know that isn't in code or docs?	Note to self, vault entry
Workspace	Any untracked files, stale branches, temp dirs?	`git status` clean, no `.tmp`

If a surface isn't applicable, tag it n/a — don't fabricate evidence.

The handoff note

End every multi-step session with a handoff. Format:

## Handoff — <date>

**Done:** [list of completed work, with PR/branch links]
**In progress:** [what was started but not finished]
**Loose ends:** [bugs, tech debt, follow-ups]
**Decisions:** [non-obvious choices and why]
**Next steps:** [what to do first next session, in order]

Save it: commit to the repo, paste it as the session's last message, both.

When to skip

Single-question Q&A
Throwaway experiments
Sessions that produced nothing (deleted the work, no code change)

When in doubt

Do the closeout. The cost is 2 minutes. The cost of NOT doing it is the next session starting from zero.

Anti-patterns

Ending with "done" while work sits uncommitted or untested.
Fabricating evidence for a surface that was not checked.
Deleting artifacts instead of recording retention.
Leaving a running status as a permanent state.

Verification Checklist

[ ] All six surfaces are tagged verified, pending, or n/a.
[ ] Runtime behavior was checked, not inferred.
[ ] Handoff note has done, in-progress, loose ends, next steps.
[ ] Every output reference resolves.
[ ] Workspace has no unexplained untracked or temp files.

Terminal State

Every exit path writes a terminal status: completed, failed, or interrupted. A crash must leave running as an unambiguous signal, not a permanent lie.
Repair stale running rows at startup with an explicit age threshold.
Check that every output reference resolves before closeout; a dangling locator is a data-loss report.
Recompute derived aggregates only after the terminal write, and record the config fingerprint used.
Closeout is not deletion: keep summaries and artifact references, drop only what retention policy names.

Install and discovery

Contents