/session

What it does

Writes a handoff entry to docs/SESSIONS.md capturing what shipped, what’s in flight, gotchas, and what the next session should do first.

When to use

End of any session with in-flight work
End of a session that made non-trivial changes
End of a session that uncovered info the next session will need
Start of a new session: /session last to read the previous handoff

Usage

/session rate-limit-done          # write new handoff
/session last                     # read the most recent one

What gets captured

## YYYY-MM-DD — <Title>

What shipped:
- <change> — <file:line or commit>

In flight (not yet shipped):
- <what> — <blocker or next step>

Gotchas the next session should know:
- <anything surprising>

Next session should probably:
- <suggested next step>

Entries are prepended (newest at top), so /session last always returns the current one.

How it gathers info

Claude pulls context programmatically before asking you:

git log --since="6 hours ago" --oneline
git status
git diff --stat

Then asks you to fill in gaps — what’s blocking, what’s surprising, what comes next.

Follow-ups it suggests

If the session:

Made a design choice → run /decision
Fixed a non-obvious bug → add to docs/KNOWN-ISSUES.md
Shipped a tracked gap → manually mark it shipped YYYY-MM-DD (commit: <hash>) in the relevant docs/*-GAPS.md file (never delete the section)
Hit a milestone → update CLAUDE.md status

Why it matters

A session without a handoff is wasted institutional knowledge. The next session (human or AI) re-discovers what you just figured out. /session is the cheapest form of continuity you can add.

/ship — runs before commit; /session runs after
/decision — often a follow-up to a session with trade-offs