session-handoff

Session Handoff

Context dies between sessions. The next session re-reads files, re-discovers decisions, and re-hits the same trap that cost an hour last time. This skill freezes the session's working state into one document built to be read cold.

Step 1: Mine the session

Extract from the current conversation, not from memory of what should have happened:

• What was accomplished: only things actually finished and verified. Half-done work is listed as half-done.
• Decisions made and why: especially decisions that reversed an earlier approach. The "why" is the part the next session cannot reconstruct.
• What is in progress: exact state, which file, which step.
• Next steps: concrete and ordered, with the first one precise enough to start typing immediately.
• Gotchas: everything that failed and how it was fixed, environment quirks, commands that need specific flags, things that look broken but are fine.
• Key paths and commands: the files that matter and the exact commands to run (build, test, deploy, resume).

Step 2: Write the handoff

Default target: START_HERE.md in the project root (or append a dated section to an existing one, newest at the top). Format:

# Start Here: <date>

## TL;DR
Two sentences: where the project is, and the single next action.

## Done this session
## In progress
Exact state, file, and step for each item.

## Next steps (in order)
1. The first one must be executable immediately, with the exact command or file.

## Decisions and why
## Gotchas
What burned time this session, so it does not burn time again.

## Key paths and commands

Step 3: Verify readability cold

Reread the document as someone with zero context: no session shorthand, no "the fix we discussed", no codenames invented mid-conversation. Every reference names its file. If a next step depends on a decision, the decision is in the document too.

On resume

When a new session starts with "where did we leave off": read START_HERE.md, confirm the state still matches reality (files may have changed since), and start on next step 1. Flag divergence instead of following a stale plan.