The /handing-off-work Skill

What it does

handing-off-work saves the half of a session that git cannot: why the code looks the way it does, what was tried and rejected, and the exact next move.

A session ends with two kinds of knowledge. The repo recovers state. The session alone holds reasons. Most handoffs fail by swapping them — writing intentions as facts, or leaving dangling references only the original conversation can resolve.

State comes from the repository. Reasons come from the session. Never swap them.

Write for a reader with no memory of the session.

The output is one Markdown handoff file a cold reader can act on without asking “what did we mean?”

When to reach for it

• The session is ending with unfinished work
• Context is about to compact or reset
• Work is moving to another harness (Claude Code, Codex, Cursor, Copilot) with no shared history
• An autonomous run stopped partway and a human or agent takes over
• A branch is passed to an engineer who wasn’t in the session
• You’re resuming from a handoff and need to know how far to trust it

Reach for something else when:

Situation	Better fit
Planning work that hasn’t happened yet	plan-with-me
Describing a finished change for review	A PR description
Permanent docs / ADRs / runbooks	Real documentation — handoffs decay
“What did you just do?”	A reply in the conversation
Work is finished, merged, or abandoned	No handoff needed

Prerequisites

Read access to the repository and permission to write one Markdown file. The skill uses git for state sections and marks claims as unverified when git isn’t available. It can run unattended at the end of an autonomous session.

How it works

1. Read state from the repo — Branch, HEAD, dirty files, unpushed commits, and what tests currently report. Memory is not allowed to invent this.
2. Recover reasons from the session — Decisions (choice + why + where in code) and dead ends (what failed and why), not a diary of every edit.
3. Write the resume instruction first — One concrete next action executable without reading the rest. If you can’t state it, the work needs a decision or deeper grounding.
4. Draft against relevance — Would this line change what the next agent does? Aim for one to two screens.
5. Strip session glue and secrets — Kill “as discussed”, “that file”, invented names; never paste tokens or personal data.
6. Cold-read check — Read as a stranger: first action executable, state matches git, nouns resolve from doc + repo.
7. Write the file and say how to hand it over — Path plus how the next person should open it.

What you get

A handoff document with Resume here, Goal, State, Decisions, Tried and abandoned, Code changes, Environment and commands, Gotchas, and Open questions.

Full templates and the resume checklist live in the source skill.

Common questions

Isn’t this just a PR description?
No. A PR argues a finished change is correct. A handoff says where unfinished work stopped and what to do next.

Should decisions stay in the handoff forever?
No. Handoffs decay as the branch moves. Promote lasting decisions into real docs; treat the handoff as disposable.

What if the next step is undecided?
Put it in Open questions and start plan-with-me. A handoff records decisions already made; it doesn’t invent the plan.

It’s working if

• The first section is a concrete next action, not “continue the refactor”
• Every state claim matches what git (and tests) actually returned
• Dead ends are findings with reasons, not a narrative of attempts
• A stranger can resolve every noun from the document plus the repository
• Secrets and session shorthand are gone

Where it fits

Use after plan-with-me when a planned effort spans sessions, or after diagnostics when you’ve found a root cause and need someone else to finish the fix. Pair with debug-flow when the trail of a bug has to survive a context reset.