Handoff

Handoff — pass the baton without losing the work

1. Purpose

Long sessions accumulate state that lives nowhere durable: what's in flight, what was decided five minutes ago, which file is half-written, what the user just asked for. When the context resets or a new agent takes over, that state is lost and the work gets re-done. This skill captures only that volatile state into a single handoff document, drops it in the OS temp directory (so it never pollutes the repo or git), and points the next agent at everything that's already persisted rather than restating it.

The governing instinct, in this repo's spirit: don't recreate stuff. The context/ wiki, context/log.md, outputs/, inbox/, and raw/ already hold the durable knowledge. The handoff is the thin layer of "here's where we are right now and what to do next" that those artifacts don't capture — nothing more.

2. Operating principles applied

See .claude/OPERATING_PRINCIPLES.md.

• #4 Separate planning from execution — a handoff is a plan for the next session: it states the goal, the state, and the next concrete steps so the receiving agent executes cleanly instead of re-planning.
• #5 Be intentional about the intervention point — flag, explicitly, the decisions still waiting on the user's judgment, so the next agent engages them at the right moment instead of guessing.

This skill is lighter on the Golden Rule than most — it's mechanical — but it still takes one input from the user: what the next session is for. If that wasn't passed as an argument, ask once (Section 4), then proceed.

3. Step 1 — Orient before you summarize (Wiki Contract)

Per .claude/WIKI.md, the handoff must reference, not duplicate. Before writing a word:

1. Skim context/index.md and the tail of context/log.md — these already record what's been ingested, decided, and built. The handoff links to them; it does not re-summarize the wiki's contents.
2. Note any artifacts produced this session — files under outputs/, staged material in inbox/, archived sources in raw/, new pages in context/. These get referenced by path, never pasted in.
3. Identify the genuinely volatile state that exists nowhere on disk yet: the in-flight task and how far it got, pending user decisions, temp files, open browser/tool state, and the immediate next action.

4. Step 2 — Confirm the focus (one question, only if needed)

If the user passed an argument, treat it as the next session's focus and tailor the document to it (lead with what advances that goal; demote the rest).

If no argument was passed, ask one short question and wait:

"What will the next session be used for — finishing the current task as-is, or a specific next focus? One line is fine."

Don't interrogate further. This is a fast operation.

4.5 Step 2.5 — Check & update memory (mine the session)

A handoff is the consolidation point for everything durable the session produced. Two layers persist across a /clear, and the ephemeral handoff doc is neither of them: native memory (facts about the user and how to work with them) and the context/ wiki (project knowledge). Before writing the handoff, check and update memory, and verify the wiki caught the project facts.

A. Mine the user → update memory (user + feedback). Read back over the user's own turns this session — questions, instructions, corrections, asides, speech-to-text quirks — and distil what they reveal about who they are, what they ask for, and what they like:

1. Continuous profile / style — refine <memory>/user-continuous-profile.md and append a short dated observation for this session (this is what makes it continuous — even after a /clear the next session knows them a little better). Voice signals also go to context/writing-style.md.

2. New feedback / correction / preference — if they corrected you or told you how they want things done, update (or create) the relevant feedback-* memory. A correction you don't capture, you'll repeat.

3. New fact about the user — update user-<name>.md if role/situation/identity shifted.

   Update, don't duplicate; be honest and specific ("reacts to artifacts; build-and-show beats long upfront questions" — not "likes good work"); record one-offs as dated data points, and flag contradictions rather than silently overwriting (Wiki Contract).

B. Verify project knowledge landed in the wiki — do NOT put it in memory. Project facts (decisions, deals, research, status) belong in context/ + context/log.md, captured during the session per the Wiki Contract — not in native memory, and not only in the ephemeral handoff doc. At handoff, confirm they're there; if anything durable is still only in the conversation, write it back now (or flag it). Routing rule: facts about the user and how to work with them -> memory; project facts -> the wiki.

Then reference the profile + any updated memories in the handoff doc (Section 5) under "Already persisted".

Memory dir: Claude Code's per-project auto-memory (~/.claude/projects/<project-slug>/memory/, indexed by MEMORY.md) — when your Claude Code build has it enabled. If it doesn't, skip part A and record durable user facts in context/profile.md / context/writing-style.md instead. If the continuous profile doesn't exist yet, create it (frontmatter type: user) and add it to MEMORY.md.

5. Step 3 — Write the handoff to the OS temp directory

Location (never the workspace): write to the OS temp dir. Resolve it at runtime — do not hardcode a path:

DIR="${TMPDIR:-/tmp}"; STAMP="$(date +%Y%m%d-%H%M%S)"
OUT="${DIR%/}/digital-workforce-handoff-${STAMP}.md"

Use the Write tool to create the file at that resolved absolute path. The temp dir is intentional: the handoff is ephemeral working state, not a committed artifact, and keeping it out of the repo respects the portability rule (no stray machine-specific files in git).

Document structure (omit any section that's empty — don't pad):

# Handoff — <one-line title> — <YYYY-MM-DD HH:MM>

## Next session focus
<the user's stated focus, or "continue current task as-is">

## Goal / what we're actually trying to achieve
<the outcome, in 1–3 sentences>

## State right now (the volatile part — this is the point of the doc)
- In-flight task: <what> — <how far it got> — <exact next action>
- Temp / working files: <absolute paths in OS temp, if any>
- Open tool/browser state: <e.g. "Chrome tab logged into the vendor portal, on /file/<id>">
- Anything half-written: <path + what's left>

## Pending decisions for the user (engage their judgment here)
- <decision> — <options / why it matters>

## Already persisted — read these, do NOT redo them
<reference by path/URL; one line each>
- `context/index.md` — wiki catalog; orient here first
- `context/log.md` — ledger of what's been ingested/decided/built (read the tail)
- `<memory>/user-continuous-profile.md` — the continuous read on the user (updated this session per Section 4.5)
- `outputs/...`, `inbox/...`, `raw/...`, `context/...` — artifacts from this session
- External: <Notion/URL/ticket references, not their contents>

## Suggested skills for the next agent
<which skills to invoke, and why — see Section 6>

## Watch-outs
- <gotchas, fragile steps, things that failed, constraints (e.g. login-gated tools)>

Rules while writing:

• Reference, don't duplicate. If something is already in context/, outputs/, a commit, a PRD, or a URL, link it by path — never paste its contents. The handoff should be short because the artifacts carry the weight.
• Redact secrets and PII. No API keys, tokens, passwords, or sensitive personal data in the doc. If a value is needed, name it (e.g. "the service session cookie") without reproducing it.
• Be concrete about the next action. "Resume extraction at file 4 of 80, URL /file/<id>, write transcript to raw/" beats "continue the extraction work."

6. Step 4 — Suggested skills section

Always include a Suggested skills section recommending which skills the next agent should invoke, tied to the focus. Pick from what's available in this repo, e.g.:

• /onboard — if the context wiki is empty or stale
• /sort-knowledge — if inbox/ has unprocessed material to synthesize
• /brain-dump — to capture undocumented context before producing output
• /research-analyst, /strategic-advisor, /comms-expert, /ops-powerhouse — the digital employees, when the next step is their kind of work
• /chief-of-staff — when the next step spans several employees
• /wiki-lint — if the wiki may have drifted (contradictions, orphans, staleness)

Name the specific skill and the specific reason, not a generic list.

7. Step 5 — Tell the user and log lightly

• Print the absolute path of the handoff file so the user (or the next session) can find it: "Handoff written to <path>."
• Give a one-line summary of what it covers and the single most important next action.
• Append a one-line HANDOFF: entry to context/log.md (timestamp via date "+%F %H:%M") noting a handoff was written and its focus — so the ledger reflects the pause point. Do not copy the handoff contents into the log.

8. Pro tips

• This is state capture, not a status report. If you find yourself re-explaining what's already in the wiki, stop and link it instead.
• The temp dir is a feature. Handoffs are disposable. A new one supersedes the old; don't accumulate them in the repo.
• Write it before you need it. The best time to hand off is before a context reset, while the volatile state is still fully in view — not after, when it's already degraded.
• Mine the user, not just the work. The continuous profile (Section 4.5) is the compounding asset — a session's questions, corrections, and asides reveal style the work artifacts never capture. Even a routine handoff should leave it a little sharper.
• Resuming? A fresh agent should read the handoff, then immediately follow its "Already persisted" links (starting with context/index.md) before acting, so it rebuilds shared context without redoing work.