Create Handoff

Create Handoff

Write a session handoff file at .turbo/handoff/<YYYY-MM-DD>-<slug>.md so a fresh session can pick up where this one left off.

Step 1: Resolve the Target Path

Get today's date: date +%Y-%m-%d.

Pick a slug for the current task:

• Lowercase
• Replace non-alphanumeric characters with hyphens
• Collapse consecutive hyphens
• Trim leading and trailing hyphens
• Truncate to 40 characters at a word boundary

If the work is anchored to an existing plan at .turbo/plans/<slug>.md, reuse that plan's slug verbatim.

The user may pass an explicit slug or output path; honor it.

Resolve the repo root with git rev-parse --show-toplevel, except inside a linked worktree — where git rev-parse --git-dir differs from --git-common-dir — in which case use the parent of the common dir, so the handoff lands in the main checkout rather than in a worktree that is destroyed with its branch.

The target path is .turbo/handoff/<YYYY-MM-DD>-<slug>.md under that root. A generated slug takes -2, -3, and so on until the path is free. When the user supplied the slug or path and it already exists, use request_user_input to offer overwrite, a numeric suffix, or a different slug.

When an open decision will outlive the rest of the session's state, still unresolved while the work around it is finished, give it its own handoff. Everything else stays in a single file. Slug the split handoff for that decision rather than appending a collision suffix, and write it to stand alone.

State the chosen path before continuing.

Step 2: Gather Session State

Run git status --short to see uncommitted changes in the working tree.

Survey the conversation context for:

• Current task: what is being worked on, in one or two sentences
• Workflow status: where in the workflow this session is (drafting, refining iteration N, applying findings, implementing step M of K, investigating, blocked on Q, etc.)
• Active artifact: path to the plan or other file at the center of the work, if one exists
• Open decisions: questions raised but not resolved, choices the user is still weighing, escalations awaiting input
• In-flight changes: staged or unstaged edits that are not yet committed; what each change is doing and what is missing
• Closed avenues: approaches that were built or tested and then abandoned, with the observed evidence that ruled them out
• Next step: the first concrete action the new session should take. When the user has stated what they want to work on next, that intent leads and any work left in flight is ordered after it; say so in the same statement when that work should not resume at all

Read .turbo/improvements.md under the repo root resolved in Step 1 if it exists and note any entry this handoff takes over. When no entry clearly matches, leave the backlog alone.

When something is genuinely unclear and would leave a gap in the handoff, use request_user_input to resolve it. Default to inferring quietly when the conversation makes the answer clear.