Why this exists
My longest projects survived between sessions for one reason: I left myself NEXT-TIME-START-HERE notes by instinct. Two sentences on where things stood, the next action, and whatever trap I had just climbed out of. Whenever I skipped the note, the next session paid for it. The first half hour went to re-reading files, re-deriving decisions I had already made, and, reliably, re-hitting the exact same trap that cost an hour the time before.
Context dies between sessions. The code survives, but the reasoning around it does not: why we abandoned approach A, which command needs that one flag, which thing looks broken but is fine. This skill formalizes the note I used to write by instinct, gives it a fixed structure, and adds the one discipline my instinct lacked: a cold-read check, so the note still makes sense to someone (including future me) with zero memory of the session.
How it works
- It mines the actual session From the conversation, not from memory of what should have happened: what was finished and verified, what is half-done (listed as half-done), the decisions and why, everything that failed and how it was fixed, and the exact commands that matter.
- It writes one document with a fixed shape TL;DR, done, in progress, ordered next steps, decisions and why, gotchas, key paths and commands. If a START_HERE.md already exists it appends a dated section at the top instead of overwriting history.
- It rereads the note as a stranger No session shorthand, no "the fix we discussed", no codenames invented mid-conversation. Every reference names its file, and any next step that depends on a decision carries the decision with it.
- It resumes without trusting itself Next session, "where did we leave off" reads the note, confirms the state still matches reality (files change between sessions), and starts on next step one. If reality diverged, it flags that instead of following a stale plan.
Step by step (for first-time users)
-
At the end of a session, type
/session-handoffOr just say "wrap up". Do it while the session is still open; the conversation is the source material. - Skim the draft it writes Check the "in progress" entries especially. If something is described as done that you only think is done, correct it now, cheaply.
- Make sure next step one is typeable The first next step should contain the exact command or file. "Continue the refactor" fails the test; "run the test suite in the api folder, two tests still red" passes.
- Close the session with a clear conscience The note lives in START_HERE.md at the project root, dated, newest section first.
- Next session, open with "where did we leave off" It reads the note, verifies against the current files, and picks up where you stopped instead of where it guesses you stopped.
What the handoff captures
| Section | Why it earns its place |
|---|---|
| TL;DR | Two sentences: where the project is and the single next action |
| In progress | Exact state, file, and step; half-done work labelled as half-done |
| Next steps, ordered | The first one is executable immediately, command included |
| Decisions and why | The "why" is the one thing the next session cannot reconstruct |
| Gotchas | What burned time this session, so it does not burn time again |
Honest take
What it does well: The cold-read check is the difference between a note and a handoff. Session notes are usually written in session dialect: "use the second approach", "skip the broken one". They feel complete when you write them and read like riddles a week later. This skill strips the dialect out. The other strength is honesty about state: tests not run are recorded as not run, and half-done work is never rounded up to done, because an optimistic handoff is worse than none.
What it does not do: It does not replace version control, project documentation, or a task tracker. It captures one session's working context, nothing more. It also cannot recover what was never in the conversation: if you made a decision in your head and never typed it, the handoff cannot know the why. And it deliberately keeps secrets out of the note, even ones that appeared during the session, because START_HERE.md tends to get committed.
When to use it: At the end of any session on a project you will not touch again for days. Before handing work to another person or another agent. And especially when you stop mid-task: the messier the stopping point, the more the handoff is worth, because that is exactly the state you will not be able to reconstruct cold.