Handoff

On invocation: announce "Running paad:handoff v1.31.0" before anything else.

Handoff

Experimental. Arguments, file format, and behavior may change — or this skill may be withdrawn — in any release, including a patch release. The semver promise the settled skills carry does not apply here. If you build a workflow on it, pin your plugin version and file what breaks.

Writes a handoff.md that lets a fresh session continue this one's work, and reads it back on the other side.

Claude Code already solves most of this, and knowing which part it doesn't is the whole point. /compact summarizes and keeps working, but the summary it carries is machine-authored, lands unreviewed, and lives inside the transcript where you cannot edit it. --continue and --resume restore the full prior conversation, which re-pays the context cost you were trying to escape. /clear gives a genuinely empty session and carries nothing forward. handoff is worth running for exactly one reason: the carried state is a file a human can read and correct before anything is built on it. A handoff nobody reviews is a worse /compact — same summary, more ceremony. Say so rather than letting the review get skipped.

The failure mode is not omission. Left to itself, a competent agent writing a handoff keeps the expensive material well: the approaches that were tried and abandoned, the reasons behind them, constraints the user stated once in passing. What it gets wrong is the cheap material — a test's file path, which changes are in the last commit, a line number, who said a quoted sentence. Those are the claims a tool could have settled in seconds, and they arrive in exactly the same confident register as the parts that are right. A fresh session has no memory to catch them with. So verify what is checkable before writing it down, and mark what is not.

Mode selection and saving:

digraph handoff_save {
  "Argument given?" [shape=diamond];
  "Use the named mode" [shape=box];
  "Conversation above this invocation?" [shape=diamond];
  "Say: saving, session has history" [shape=box];
  "Resume flow, below" [shape=box];
  "handoff.md in .gitignore?" [shape=diamond];
  "Suggest adding it, never add it silently" [shape=box];
  "Verify every checkable claim with tools" [shape=box];
  "Claim survived verification?" [shape=diamond];
  "Write it as fact" [shape=box];
  "Correct it, or mark it inferred" [shape=box];
  "Write handoff.md with the Write tool" [shape=box];
  "Name the unverified claims, ask for review" [shape=box];
  "Announce the artifact" [shape=box];

  "Argument given?" -> "Use the named mode" [label="save or resume"];
  "Argument given?" -> "Conversation above this invocation?" [label="no"];
  "Conversation above this invocation?" -> "Say: saving, session has history" [label="yes"];
  "Conversation above this invocation?" -> "Resume flow, below" [label="no"];
  "Use the named mode" -> "Say: saving, session has history" [label="save"];
  "Use the named mode" -> "Resume flow, below" [label="resume"];
  "Say: saving, session has history" -> "handoff.md in .gitignore?";
  "handoff.md in .gitignore?" -> "Suggest adding it, never add it silently" [label="no"];
  "handoff.md in .gitignore?" -> "Verify every checkable claim with tools" [label="yes"];
  "Suggest adding it, never add it silently" -> "Verify every checkable claim with tools";
  "Verify every checkable claim with tools" -> "Claim survived verification?";
  "Claim survived verification?" -> "Write it as fact" [label="yes"];
  "Claim survived verification?" -> "Correct it, or mark it inferred" [label="no"];
  "Write it as fact" -> "Write handoff.md with the Write tool";
  "Correct it, or mark it inferred" -> "Write handoff.md with the Write tool";
  "Write handoff.md with the Write tool" -> "Name the unverified claims, ask for review";
  "Name the unverified claims, ask for review" -> "Announce the artifact";
}

Resuming:

digraph handoff_resume {
  "handoff.md exists?" [shape=diamond];
  "Say so, offer to save one instead" [shape=box];
  "Read it, summarize in a few lines" [shape=box];
  "Recorded commit matches HEAD?" [shape=diamond];
  "Report the drift before asking" [shape=box];
  "Ask: proceed?" [shape=diamond];
  "Stop, leave the file alone" [shape=box];
  "Check the files and state it names" [shape=box];
  "Everything matches?" [shape=diamond];
  "Report every mismatch, ask again" [shape=box];
  "Start the recorded next step" [shape=box];
  "Leave handoff.md in place" [shape=box];

  "handoff.md exists?" -> "Read it, summarize in a few lines" [label="yes"];
  "handoff.md exists?" -> "Say so, offer to save one instead" [label="no"];
  "Read it, summarize in a few lines" -> "Recorded commit matches HEAD?";
  "Recorded commit matches HEAD?" -> "Ask: proceed?" [label="yes"];
  "Recorded commit matches HEAD?" -> "Report the drift before asking" [label="no"];
  "Report the drift before asking" -> "Ask: proceed?";
  "Ask: proceed?" -> "Check the files and state it names" [label="yes"];
  "Ask: proceed?" -> "Stop, leave the file alone" [label="no"];
  "Check the files and state it names" -> "Everything matches?";
  "Everything matches?" -> "Start the recorded next step" [label="yes"];
  "Everything matches?" -> "Report every mismatch, ask again" [label="no"];
  "Report every mismatch, ask again" -> "Start the recorded next step" [label="user confirmed"];
  "Start the recorded next step" -> "Leave handoff.md in place";
}

Arguments

• /handoff — infer the mode. Conversation above this invocation means you are saving; an empty session means you are resuming. Say which way it went, in one line, before acting.
• /handoff save — write a handoff regardless
• /handoff resume — read the existing handoff regardless

The inference is a convenience, not a guess worth defending. If it picks wrong, the user says save or resume and you obey without arguing.

Saving

1. Check .gitignore

If handoff.md is not ignored, say so and suggest adding it. Suggest — do not edit .gitignore yourself. It is a tracked file and the user may have reasons.

2. Verify before you write

This is the step that makes the skill worth running. Every claim below is checkable with a tool in seconds, and every one of them is a claim agents get wrong from memory:

If a claim cannot be settled, it does not become a fact. Either drop it or mark it inferred.

3. Write the file

Use the Write tool, never a shell redirect. Claude Code snapshots files its own file tools touch; a bash > handoff.md has no recovery copy anywhere, and neither does git, since the file is ignored.

# Handoff — <one-line task name>

Written <date time> · branch `<branch>` · commit `<short sha>`
Uncommitted: <one line — what is dirty, what is staged>

## Goal
What we are trying to achieve, and what "done" looks like.

## Decisions
Chose X over Y, because Z. One line each.

## Ruled out
What was tried, how it failed, and how far it got. One line each.

## Constraints
Things the user said that exist nowhere on disk. Quote them.

## Next step
The single immediate action, with the file and line to start at.

## Verify
The command that says whether it worked.

## Unverified
Anything above that could not be checked, marked as inferred.
Delete this section if it is empty — do not pad it.

"Ruled out" is the section that earns the file. Everything else is recoverable — a fresh session can read the code, run git log, work out the goal. What it cannot recover is that forty minutes already went into proving an approach doesn't work. Without that line, it spends them again.

Write down what a fresh session cannot reconstruct, and nothing else. No architecture tour, no narrative of how the session went, no restating what git diff already shows. Those feel thorough and are pure padding, and padding is not harmless here: it makes the file long enough that the review gets skimmed, and the review is the only reason this skill beats /compact.

4. Ask for the review that matters

Do not close with a general disclaimer. "Please review, AI can make mistakes" is true of everything and therefore aims at nothing — it gets skimmed, and inference reads exactly like recall.

Name the specific claims you are least sure of and say what depends on them:

Two things to check before you rely on this. I inferred the next step from what we were doing rather than from anything you said outright, and I could not confirm the second constraint is still live — it came from early in the session. Everything downstream is built on both.

If everything in the file was verified, say that instead, plainly. An honest "all of this was checked against the repo" is a better prompt to read it than a manufactured doubt.

5. Announce the artifact

End with the file you touched. Say it even though the user asked for it and watched it happen — a handoff sitting unnoticed in the working directory is the same as no handoff:

Files written or updated:
  new      handoff.md

On a resume, the same block covers whatever the recorded next step changed. Source and test files need only a count and a pointer — 4 source files changed in src/dbsync/ (see git diff) — but handoff.md itself is named every time.