haacked/dotfiles/handoff

Session Handoff

Bridge between agent sessions. Optimized for the next session reading the doc cold, with full tool access but zero conversation history.

Modes

Parse the first argument from user input.

Common: resolve the storage path

Always start with the helper. Never construct the path yourself.

result=$(scripts/handoff-path.sh)
status=$(echo "$result" | cut -f1)   # existing | new
path=$(echo "$result"   | cut -f2)
scope=$(echo "$result"  | cut -f3)   # repo:org/name or dir:/abs/path

The helper writes to <repo-root>/.notes/handoff.md inside a git repo, or ~/.agents/handoff/dir-<hash>.md outside one.

Create mode (no argument)

This is the default. Write a handoff doc tuned for the next agent session.

Step 1: Confirm the scope

Tell the user the resolved scope (e.g., "Writing handoff for repo:haacked/dotfiles at .notes/handoff.md.").

If status is existing, archive the previous handoff before writing the new one so a trail is preserved. Read the old one first (you may want to carry forward still-relevant content like references or ruled-out approaches), then archive it:

archived=$(scripts/handoff-archive.sh "$path")

The archive script moves the file to <dir>/handoff-archive/<basename>-<YYYYMMDD-HHMMSS>.md and prints the new path. Mention to the user that you archived the previous one and where it went.

Step 2: Bail if there's nothing to hand off

If the conversation contains no concrete work (no files read, no commands run, no decisions made), tell the user:

No session work to hand off yet. Run /handoff again after you've made progress.

Then stop. Do not write a placeholder handoff.

Step 3: Gather state actively

Do not write the handoff from memory of the conversation. Memory produces narrative; state produces handoffs. Before filling any section, gather concrete state:

• Run git diff HEAD --stat and git status to get an overview of what changed.
• Read the files central to the handoff directly with the Read tool (or run git diff HEAD -- <path> for a focused diff); don't trust your recall of their current contents, and don't load the full unbounded diff.
• Re-run failing tests or commands you've mentioned, so the verification section reflects reality.

Then capture the git snapshot for embedding:

scripts/handoff-snapshot.sh

This emits a markdown block with branch, HEAD, upstream, and the dirty working tree. Embed it verbatim under the ## Snapshot heading.

Step 4: Fill the template

Start from templates/handoff.md. Fill every section from the state you just gathered. Optimize for the next agent session specifically:

• Pointers over prose. Cite file.ts:42 instead of paraphrasing code. The next session can read.
• Decisions over events. Don't narrate the session ("first I tried X, then Y"). Record outcomes: what we chose, why, what was ruled out.
• Concrete next action. Name the file, the function, the failing test. "Continue the refactor" is wrong; "edit foo.ts:42 to handle the null case, then run pnpm test bar.spec.ts" is right.
• Decay-aware. The snapshot timestamps the doc. Don't pretend it stays fresh: the doc tells the reader to trust the code over the doc if they conflict.
• One page. If you're past ~1 page, the doc is wrong: split the work smaller or commit in-progress state to a branch and let the diff carry the load.

Anti-example pair, internalize the difference:

• ❌ "We spent the session trying to understand why the tests fail."
• ✅ "foo.ts:42 throws when opts is null; pnpm test bar.spec.ts currently fails at line 67."

Sections to fill (see template for prompts):

1. Goal (one sentence, outcome not task)
2. Status (concrete bullets: ✅ works, 🚧 in progress, ❌ broken)
3. Next action (file:line specific)
4. Open decisions (options + tradeoff + leaning, or "None.")
5. Ruled out (approach + one-line reason)
6. Verification (copy-pasteable commands)
7. Key locations (file paths + one-line what's there)
8. Gotchas (non-obvious traps, or "None.")
9. References (PR/issue/Slack links, or omit section)

Deliberately exclude: diff dumps, session narrative, re-explanations of readable code, speculation about future phases.

Step 5: Write the file

mkdir -p "$(dirname "$path")"

Then write the filled-in markdown to $path. If a .notes/ directory exists alongside the file, verify it's gitignored (warn the user if not).

Step 6: Report

Tell the user the path you wrote. One line. Suggest next steps:

Wrote handoff to <path>. Next session: open this repo and run /handoff resume.

Resume mode (resume)

Bootstrap the current session from an existing handoff.

Step 1: Read

If status is new, tell the user no handoff exists for this scope and stop.

Otherwise, read the file at $path.

Step 2: Reconcile with current state

Run handoff-snapshot.sh again and compare to the snapshot embedded in the doc:

• Same branch + HEAD: doc is fresh, proceed.
• Same branch, HEAD moved: warn the user that work happened since the handoff was written. Suggest running git log <doc-head>..HEAD to see what changed.
• Different branch: ask the user whether to switch branches or treat the handoff as reference only. In reference-only mode, present Goal and Ruled out as probably still valid; treat Status, Next action, and Snapshot as stale and skip them in the summary.
• Working tree differs from snapshot: note it, don't block.

Also check relevance: if the handoff's Goal has no relationship to the current working directory or recent git activity, say so explicitly:

This handoff describes [goal] but current state suggests different work. Treat as reference only, or archive it and start fresh.

Step 3: Summarize and propose action

Give the user a tight summary:

• Goal (verbatim from doc)
• Status (verbatim, unless reference-only mode)
• The Next action the doc names (unless reference-only mode)

Then propose: "Do you want me to start on the next action, or do something else first?" Do not begin the work unilaterally, resuming is the user's call.

Step 4: Offer to archive (after the user decides)

Hold the archive question until the user has confirmed what they want to do next (accept the proposed action, name a different action, or say they're unsure). Then offer to archive:

archived=$(scripts/handoff-archive.sh "$path")

Default to yes since a stale doc on disk encourages re-loading outdated state. Report the archive path so the user knows the trail exists. If the user is still deciding or declines, leave the file in place.

Show mode (show)

Just print the file contents and stop. No interpretation, no reconciliation. Use when the user wants to see the handoff without acting on it.

If the file doesn't exist, say so and stop.

Path mode (path)

Print the resolved storage path and the scope. One line. Use when the user wants to know where the handoff lives (e.g., to gitignore it or open it in an editor).

Boundary: /handoff vs /note vs plans

If the handoff outgrows one page or starts capturing knowledge that outlives the task, promote the relevant parts to /note (technical) or a plan (multi-stage work) and keep the handoff tight.