handoff

# Handoff

Compact the current conversation into one self-contained, tool-agnostic Markdown document under `docs/handoffs/` that any fresh agent can resume from by reading only that file. Reference committed artifacts by path or URL; inline anything not yet pushed; redact secrets and PII.

## Step 1: Determine the slug and any focus

Derive a kebab-case `<slug>` from the user's arguments if given (e.g., "finish the migration tests" → `migration-tests`), otherwise from the conversation's most recent active thread; when no arguments were passed, state the inferred topic and slug in one line before continuing.

Record a **Focus for next session** only when the conversation gives a clear signal — verbatim user arguments, or an explicitly stated next objective. Never manufacture one: with no signal, omit the focus and leave forward direction to the resumer.

## Step 2: Locate the doc; decide create, enhance, or overwrite

Resolve the root with `$CLAUDE_PLUGIN_ROOT/skills/init/references/multi-repo-detection.md` — the workspace root in a multi-repo workspace, otherwise the repo/project root. The handoff folder is `docs/handoffs/` under that root. Then branch:

- **`<slug>.md` exists** → read it, then `AskUserQuestion`: **Enhance** (merge new context; keep still-valid content and append a History line) or **Overwrite** (fresh rewrite; the prior version stays in git history).
- **No slug match but other handoffs exist** → list them (filename · title · Last updated), then `AskUserQuestion`: **Continue one** (pick via a follow-up question, then treat as Enhance) or **Create new**.
- **Folder empty or absent** → create new.

## Step 3: Classify artifacts against version control

Resolve git state so the document references what survives on another clone and inlines what does not. Per repo (per child repo in a multi-repo workspace), find the branch and short HEAD SHA for **Origin**, each path's tracked / modified / staged / untracked status, and unpushed commits via `git log --oneline @{upstream}..HEAD` (fallback `origin/HEAD..HEAD`; no upstream or detached HEAD → treat local commits as unpushed). If the directory is not a git repo, note "not a git repo" in **Origin** and inline everything.

Sort every artifact into three buckets:

1. **Tracked and pushed** → reference by repo-relative path / SHA / URL (never inline).
2. **Tracked-but-modified, staged-not-committed, or committed-not-pushed** → inline the relevant content (diff, file body, or commit message) — another clone will not have it.
3. **Untracked** → inline.

Qualify paths and SHAs with the repo name in a multi-repo workspace.

## Step 4: Draft or reconcile the document

If the conversation has not already established the codebase's current state, briefly orient in the repo first so the document's factual claims reflect what is actually there — keep it light; this grounds the doc, it is not fresh exploration.

Fill the **Handoff document template** from what was actually discussed. **New or overwrite** → write fresh. **Enhance** → keep still-valid content; update **Current state** (and **Goal**/**Next steps** if present) to current reality, dropping completed steps; preserve and extend the recorded decisions and open questions, promoting any the new work has resolved; add new artifacts; refresh **Last updated**; append one **History** line.

- Prioritize knowledge a fresh agent could not re-derive from the code or git history — decisions and why, alternatives considered and rejected, constraints, gotchas, and still-open questions. Include **Goal**, **Focus for next session**, and **Next steps** only when the conversation makes them genuinely clear; otherwise omit them.
- Never duplicate content that lives in a tracked artifact — reference it by path plus a one-line summary. Inline only bucket-2 and bucket-3 content.
- Trust git state over chat memory when they conflict; if the current state is ambiguous, say so in one line rather than guessing.
- Keep the document tool-agnostic: refer to the resuming actor as "a fresh agent" or "a new session" — never name a specific AI product.

## Step 5: Redact inlined content

Scan everything you are about to **inline** (never paths or references) against the **Redaction patterns** table and replace matches with the exact marker `[REDACTED: <kind>]`, preserving structure — e.g. `DATABASE_URL=postgres://app:[REDACTED: password]@db:5432/app`. A file whose name looks like a secret (the same set `/optimus:commit` warns about) is **never inlined with its values** regardless of tracked state — see the table's last two rows.

## Step 6: Write the document, then report and recommend

Write the filled template to `docs/handoffs/<slug>.md` under the root resolved in Step 2, creating `docs/handoffs/` if missing.

Report the written path; tell the user the document is redacted and safe to commit, and that any older handoffs in the folder remain (this is the latest for its topic). If the resolved root is a multi-repo workspace root that is not itself a git repo, note that the file is not yet under version control — suggest committing it inside a child repo or initializing version control at the root.

Recommend `/optimus:commit` so the handoff reaches the remote and other machines. Then emit the closing tip from `$CLAUDE_PLUGIN_ROOT/references/skill-handoff.md` — **Variant A**, substituting `<continuation-skill(s)>` with `/optimus:commit` and `<non-continuation-examples>` with `/optimus:code-review`, `/optimus:unit-test`. This tip is spoken to the user; it is never written into the document, which stays tool-agnostic.

## Handoff document template

Minimal-but-complete; omit any section with nothing to say — **Goal**, **Focus for next session**, and **Next steps** included, unless the conversation makes them genuinely clear. Ordering follows a cold reader's path: orient (Goal if present, Current state, decisions) → act (Next steps, if any) → reference (artifacts).

````markdown
# Handoff: <short title of the work>