| name | shutdown |
| description | Graceful end-of-session cleanup before the session is killed (Ctrl-C / closing the tab). Persists anything that would be lost (learnings worth keeping, a handoff doc if mid-task, in-flight decisions) and makes uncommitted git work safe locally. Fast and silent like an OS flushing buffers before power-off, then says "safe to shutdown". Invoke when done with a session: /shutdown, "done", "goodbye", "shutting down", "wrap up". |
Graceful shutdown
The session is about to be killed. Anything that lives only in this context dies with it.
Flush it to disk, make git safe, report in one scannable block, end. No long goodbye. This
is buffer-flush-before-power-cut, not a retrospective.
Work fast and in parallel. Skip any step that has nothing to do. Do NOT ask permission for
the local-only actions below. Invoking shutdown authorizes them. Only stop for the one gate
noted under Git.
What actually gets lost
Closing a tab / Ctrl-C does not wipe the working tree. Uncommitted files survive on
disk. What dies is in-context knowledge: things learned, decisions made, dead ends
ruled out, the "where I was" of an unfinished task. Weight effort there first.
Steps (run concurrently where possible)
-
Learnings worth keeping. Did this session produce a durable, non-obvious fact,
something you'd want a future session to know that isn't already in the repo, git
history, or your project instructions? If yes, save it where your setup keeps notes:
- A reusable fact about you / your work / a system → your memory or notes system, if you
keep one (follow its own conventions: one fact per file, an index entry, dedupe
against what's already there).
- A research finding / investigation result / takeaway → a dated session note, e.g.
~/notes/YYYY-MM-DD-{kebab-slug}.md (adjust the directory to wherever you keep them).
- Nothing durable? Say so and skip. Do not manufacture a learning.
-
Handoff doc, only if mid-task. If a task was in flight and unfinished, write a
handoff (e.g. ~/notes/YYYY-MM-DD-{slug}-handoff.md) so the next session resumes cold.
Keep it tight:
- Goal: what we're trying to do.
- State: what's done, what's left, current step.
- Next action: the literal next thing to do.
- Open questions / blockers, key files (
path:line), decisions made & why.
- Verify against reality before writing (git status, the actual files). A confidently
wrong handoff is worse than none.
- If the task is finished or there was no task, skip.
-
Git safety. For each repo touched this session (check the cwd and any repo you
edited):
git status --short + git stash list. If clean, report clean and move on.- If dirty: make a local WIP commit so nothing is implicit. If on the default
branch (
main/master), create a wip/shutdown-YYYY-MM-DD branch first, then commit.
Message: WIP: shutdown checkpoint + a one-line summary of the changes. End with your
Co-Authored-By line if you use one.
- Never push. Pushing is an outward action needing explicit permission, out of scope
for shutdown. Surface "unpushed: N commits" instead so you decide next session.
- Gate (the one stop): if committing would mix unrelated changes, or the diff looks
like it contains secrets / large generated files / something you didn't create, do
NOT auto-commit. Surface it in the report and let the user handle it.
-
Drafts & loose ends. Any unsent draft (email, chat message, comment, PR body)
produced this session: confirm it's written to a file, not stranded in chat. Any
background task / loop / cron still running: list it so the user knows it outlives the
session.
Report, then stop
One compact block, glyphs, no prose padding. Example shape:
✓ learning saved: 2026-06-25-retry-backoff-finding.md
✓ handoff saved: 2026-06-25-search-index-handoff.md (or: none, task complete)
✓ git api: WIP commit on wip/shutdown-2026-06-25 · unpushed: 1
⚠ drafts reply-draft.md written, unsent (your call)
✓ background none
safe to shutdown
End on safe to shutdown (or ⚠ shutdown: review the ⚠ lines first if any gate
tripped). Nothing after it.
