session-handoff

Session Handoff Skill

Work gets dropped at boundaries — a context window fills, a session ends, a task passes to someone else — and the next person (or agent) re-derives everything from scratch. This skill writes a tight handoff that carries the state across that boundary: the goal, what's done, where things stand, the exact next step, and the landmines. Optimised to be the first thing a fresh session reads.

Required Inputs

Ask for these only if they aren't already provided (or infer from the session so far):

• The objective — what we're ultimately trying to achieve.
• Progress — what's been done and decided so far.
• Current state — what's in-flight right now, what's working/broken, where files/branches are.
• Next step — the single most important thing to do next.
• Gotchas — dead ends tried, constraints, things that will bite the next person.

Output Format

Handoff: [task]

🎯 Objective — the goal in 1–2 lines, and the definition of done.

✅ Done so far — key work completed and decisions made (with the why for non-obvious calls), as tight bullets.

📍 Current state — exactly where things stand: branch/PR, what runs, what's failing, files touched, any half-finished change.

⏭️ Next step — the very next action, concrete enough to start immediately. Then the following 2–3 steps.

⚠️ Gotchas & dead ends — what was tried and didn't work (so it isn't repeated), constraints, sharp edges, anything surprising.

🔗 Pointers — key files (path:line), commands to run, links (PR, issue, docs) the next person needs.

Keep it skimmable — the next reader should grasp the state in under a minute.

Quality Checks

• Objective and definition-of-done are stated up front
• Current state is concrete (branch/PR, what runs, what's broken) — not "made progress"
• The next step is specific enough to act on immediately
• Dead ends and gotchas are captured so they aren't repeated
• Pointers (files, commands, links) are included; the whole thing is skimmable in ~a minute

Anti-Patterns

• Do not write a vague status ("worked on the feature") — state exactly what's done and what's not
• Do not omit dead ends — repeating failed attempts is the most common handoff waste
• Do not bury the next step — it should be obvious and immediately actionable
• Do not assume shared memory — the reader may have zero prior context
• Do not pad it — a handoff nobody reads is worthless; keep it tight and scannable

Based On

Engineering handoff / pairing-rotation practice and incident-handoff (SBAR-style) structure adapted for agent and human work.