session-handoff-resume
verified5f52d1bc-246c-41f9-9f88-80d47c47d1d0
Write a handoff note (where things stand, decisions made, exact next step) so a task can resume cleanly across sessions or agents. Use at the end of any work session, or when resuming one.
Metadata
Skill file
# Session Handoff & Resume
Use at the end of any work session, or when resuming one. A handoff note is the
difference between a clean resume and re-deriving the whole problem from scratch
(because memory of "where I was" decays the moment the session ends).
## 1. The 4-line handoff template
```markdown
# Handoff — <task>
Goal: One sentence — what are we trying to accomplish?
State: Where things stand right now. What is done, what is half-done.
Reference file paths, branch names, commit SHAs — not just prose.
Next: The single concrete action to take next. "Run X, then fix Y."
Must be specific enough to start without re-reading everything.
Blockers: Any decisions made, open questions, or things blocking progress.
Include the exact failing command + error if there is one.
```
Example:
```markdown
# Handoff — auth refactor
Goal: Migrate auth from session cookies to JWT without breaking login.
State: JWT issuance + verify util done (src/auth/token.py). Middleware half
wired — routes not yet protected. Branch: feature/jwt-auth, commit a1b2c3d.
Tests: tests/test_token.py green (12 pass), tests/test_middleware.py
failing on 3 cases (redirect loop).
Next: Fix the redirect loop in src/auth/middleware.py:get_token() — the
cookie name is hardcoded to "session" but JWT uses "access_token".
Blockers: Decided to use PyJWT (not itsdangerous). Open question: token expiry
— 15 min vs 1 hr? Not decided. Failing command:
`pytest tests/test_middleware.py::test_redirect_loop`
-> AssertionError: expected 302, got 500.
```
## 2. Where to store it (so the next agent finds it)
Store the handoff in a **predictable, discoverable place**:
| Location | When to use |
|---|---|
| `HANDOFF.md` at repo root | Cross-session, shared with other agents/humans |
| Task tracker comment | If you use a task/project manager (Jira, Linear, Task Manager) |
| `notes/` or scratchpad file | Personal working notes (see working-notes-scratchpad) |
Pick **one** canonical location and name it in the handoff. Do not scatter it.
## 3. Resuming — the read → verify → proceed loop
```text
1. READ the handoff file first (not your memory).
2. VERIFY re-establish ground truth before trusting the handoff:
- re-run the tests / failing command it mentions
- re-read the failing diff (git diff, git status)
- confirm the branch + commit SHAs match what the note says
3. PROCEED from the "Next" action, now that state is confirmed fresh.
```
```bash
git checkout feature/jwt-auth # confirm branch
git log --oneline -3 # confirm SHA matches the note
pytest tests/test_middleware.py -q # re-run the known failure
```
Never resume from memory — the handoff (and the live repo state) is the source
of truth, not your recollection of "it was almost done."
## 4. When to write a handoff
- End of every work session (even a short one).
- Before a context switch (you're about to work on something else).
- Before handing off to another agent or human.
- When you hit a blocker and are pausing to ask for help.
## 5. Handoff types: mid-debug vs end-of-task
Not all handoffs are the same. Adjust the depth to when you are resuming:
| Type | Written when | Focus |
|---|---|---|
| **Mid-debug** | You found a bug, partially isolated it, but ran out of time | Next action is the next isolation step; block is the failing command |
| **End-of-session** | You stopped at a natural boundary or end of day | Next action is the first implementation step for the next session |
| **Delegation** | You are handing work to another agent | Full brief per subagent-delegation-playbook |
A mid-debug handoff omits "what is done" (mostly nothing is done — you are still
finding the cause) and emphasizes "Current failure" + "Next isolation step."
## 6. The anti-handoff (when not to write one)
Skip the handoff when:
- You will resume within ~30 minutes and nothing will change in the interim.
- The task is trivially small (one command to finish).
- The task was *just completed* (a handoff for a finished task is redundant).
For everything else — especially anything spanning sessions or agents — write it.
## Guardrails
- Do **not** write "almost done" without a concrete next action. "Almost done" is
a vibe; "run X then fix Y" is a plan.
- Do **not** trust your memory of the state — always write the handoff down, and
always re-verify on resume.
- Do **not** store the handoff somewhere the next agent will not find it. Name the
location explicitly.
- Do include the exact failing command + error output, not a paraphrase.
- Do include branch names and commit SHAs — they pin the exact state.
## Pitfalls
- **"Almost done" with no next action** — the next session wastes 30 minutes
re-deriving what "almost done" meant.
- **Resuming from stale memory** — skipping the handoff file and acting on a
half-remembered state.
- **Vague state** — "made progress on auth" instead of "JWT util done, middleware
half-wired at middleware.py:get_token()".
- **Missing the failing command** — "tests fail" without the command and error
means the next agent has to reproduce the failure from scratch.
- **Scattered notes** — handoff fragments in three files with no canonical source.
## Verify / Checklist
- [ ] Handoff has all four fields: Goal, State, Next, Blockers.
- [ ] "Next" is a single concrete action with a command or file:line reference.
- [ ] "State" includes branch name and commit SHA, not just prose.
- [ ] "Blockers" includes the exact failing command + error output.
- [ ] The handoff location is discoverable and named.
- [ ] On resume, the handoff was read and the repo state re-verified (tests re-run).Attached files
No attached files.