Skill · Writing

session-handoff

Condenses the current session into a one-page handoff another agent or person can continue from with zero context: goal, current state, decisions and why, files touched, working commands, what was ruled out, open questions, the next 3 steps and gotchas. Use when asked for a handoff, a summary to continue later, 'write this up for the next session', before clearing context, or when passing work to someone else.

The skill itself. Agents read the name and description first and load the rest only when a task matches.

session-handoff/SKILL.md
---
name: session-handoff
description: "Condenses the current session into a one-page handoff another agent or person can continue from with zero context: goal, current state, decisions and why, files touched, working commands, what was ruled out, open questions, the next 3 steps and gotchas. Use when asked for a handoff, a summary to continue later, 'write this up for the next session', before clearing context, or when passing work to someone else."
---

# Session handoff

Write a document that lets someone with zero context pick up the work where you left it.

## Steps

1. Review the session and the current state of the work. In a repo, run `git status`, `git log --oneline -5` and `git diff --stat` to get the branch, uncommitted changes and recent commits. Note the last command results and anything left half-done.
2. Write the handoff with these sections, in order:
   - Goal: what the work is for and what done looks like, in two lines.
   - Current state: what works, what doesn't, what's half-done. Branch name and last commit if relevant.
   - Decisions: each decision made and the reason, one line each.
   - Files touched: paths, with one line on what changed in each.
   - Commands that work: exact commands to build, test, run or reproduce, copied verbatim.
   - Tried and ruled out: approaches that failed and why, so nobody repeats them.
   - Open questions: what's unknown and who or what can answer it.
   - Next 3 steps: concrete, ordered, each small enough to start right away.
   - Gotchas: env vars, flaky tests, slow steps, things that look wrong but aren't.
3. Read it as a stranger would. Replace every "it", "the fix" and "that issue" with the actual name, path or error message.
4. Save it where the user asked, or show it inline. If they want a file, suggest HANDOFF.md at the repo root and don't commit it unless they ask.

## Rules

- Under one page, about 400 words. Cut anything the reader doesn't need to act.
- No story of the conversation ("first we tried, then"). State facts.
- Paths, commands, error messages and IDs go in verbatim, in code formatting.
- Separate what you verified from what you believe; mark the latter "unverified".
- No secrets or tokens. Name the env var instead of its value.

## Example output

```
Goal: checkout rejects expired coupons; done when the #412 acceptance tests pass.
State: API check done and tested; UI message not started. Branch fix/coupon-expiry, last commit a1b2c3d.
Ruled out: checking expiry in the DB query (breaks the admin coupon list).
Next: 1) add the message to src/checkout/CouponField.tsx 2) e2e test in e2e/coupon.spec.ts 3) open the PR
Gotcha: tests need TZ=UTC or the boundary test fails.
```