handoff

Use this when

The user needs to transfer the current conversation to a fresh agent or human who must continue without guessing about the goal, completed work, evidence, constraints, or next decision.

The output is a Markdown document in ~/Desktop/_tmp/ with a descriptive filename beginning with handoff_.

Steps

1. Establish the state to hand over

Review the conversation, including the latest corrections, decisions, constraints, and any work still in progress. Identify the current goal and the point at which the next person or agent will resume.

Locate existing PRDs, plans, ADRs, issues, commits, diffs, and verification artifacts. Check the paths or URLs you will reference. Use those artifacts for details they already contain; write only the context and current state needed to connect them. Do not copy their contents into the handoff.

Distinguish completed work from proposed work, observed results from expectations, and known facts from unresolved questions. Where the conversation does not establish a fact, identify the gap rather than inventing an answer.

2. Write the required sections

Include each of these sections, even when the accurate entry is that nothing was identified:

• Current goal: State the intended result and what remains to reach it. Reference any artifact that defines requirements or acceptance criteria.
• Changes made: Summarize what changed and its current state. Link to the files, commits, PRs, or diff that hold the details. Make clear which work is pending or uncommitted when relevant.
• Verification evidence: Record checks actually performed and their results. Reference evidence files or recorded output, and identify checks that were blocked or not run.
• Untouched scope: Name relevant work or areas that this conversation did not change or investigate. Do not imply that untouched areas were verified.
• Uncertainties and open risks: Describe unresolved facts, blockers, and risks that affect continuation, with references to supporting artifacts where available.
• Off-limits areas: Carry forward explicit restrictions on files, systems, data, actions, or scope. Separate these restrictions from areas merely left untouched.
• Last decision or gate: Record the most recent decision that governs the work, or the exact unresolved gate, including whether its prerequisite or approval has been satisfied.

Use paths or URLs that the recipient can locate without the original conversation. Explain how each referenced artifact relates to the resumed task, without repeating its contents.

3. Give exactly one safe next action

Choose one concrete action that follows from the recorded state and stays within the existing constraints. Name its target and expected result so the recipient can carry it out without selecting among alternatives.

If a gate is unresolved, choose an action that can safely establish the missing fact or obtain the required decision. Do not direct the recipient to cross that gate as though it were satisfied.

Add an explicit statement of what the recipient must not assume. Address the assumptions most likely to cause a wrong continuation, such as treating uncommitted work as merged, a successful build as behavior verification, or an unanswered question as approval. Keep this statement specific to the actual conversation.

4. Save and read back the document

Resolve ~/Desktop/_tmp/ for the current user and create the folder if needed. Choose a descriptive Markdown filename with the required prefix, such as handoff_<project>_<task>.md, replacing the placeholders with the actual subject. Use a distinct filename if one already exists so an earlier handoff is preserved.

Save the document, then read the saved file back. Check that all seven required sections are present, references point to the intended artifacts, exactly one next action is named, and the prohibited assumptions are explicit.

Review it as a reader who has no access to the conversation. Correct any unexplained identifier, missing constraint, uncertain status presented as fact, or detail duplicated from another artifact. Return the saved file's full path so the recipient can open it.

Done when

• The document exists in ~/Desktop/_tmp/ under a descriptive handoff_*.md filename and has been read back.
• All seven required sections accurately describe the current conversation state.
• Existing artifacts are referenced by usable paths or URLs rather than duplicated.
• Untouched work, uncertainties, restrictions, and the last decision or gate are explicit.
• Exactly one safe next action is named, with its target and expected result.
• The recipient is explicitly told what they must not assume and can continue without guessing.