handoff · diff
git:20260807.1a09fb8 to git:20260818.99b53e9
46 added, 18 removed. Audit A to A.
---
name: handoff
description: |-
- Use when ongoing work must continue in a new conversation, session, or agent with no shared history. Triggers: 'handoff', 'prepare context for next chat', 'summarize for a new session', 'continue this in another conversation'. Not for same-chat status updates or repository documentation.
+ Use when ongoing work or conversational context must continue in a new conversation, session, or agent with no shared history. Triggers: 'handoff', 'prepare context for next chat', 'summarize for a new session', 'continue this in another conversation'. Not for same-chat status updates or repository documentation.
---
# Handoff
Produce a transfer-ready handoff for in-progress work.
## Invocation Notice
- Inform the user when this skill is being invoked by name: `handoff`.
## Writing Style
Write the handoff in the voice of a professional technical writer.
Prefer ASD-STE100 Simplified Technical English: short sentences, one instruction per sentence, active voice, and one term per concept.
Keep identifiers, commands, paths, and file names exact.
## Critical Constraints
- - Assume the recipient can only see the handoff output and nothing else.
+ - Assume the recipient will see only the handoff document and nothing else.
- Output one fully filled handoff payload in chat.
- Do not create a handoff file unless explicitly requested.
- - Do not rely on references like "above" or "earlier in this thread".
+ - Do not rely on references like "above" or "earlier in this thread"; carry the substance of conversation-only information into the handoff itself.
+ - Record, do not decide: every statement must trace to the user's words, the session's actions, or an artifact.
+ Do not infer next actions, select new work, or extend scope.
- If information is missing, write `Unknown` and specify what is needed.
+ - If a section genuinely has no items, write `None` — `None` and `Unknown` are different claims.
+ - Omit sections marked repo-only in the template when no repository is involved or repo state is irrelevant to the work.
+ - Omit sections marked only-if-established when the session produced nothing for them; never invent content to fill a template slot.
+ ## Failure Modes
+
+ - Optimistic closure: reporting work as done when its evidence (file, commit, passing check) does not exist.
+ Verify before claiming.
+ - Journey narration: recording the session chronologically ("first I tried…").
+ Record the end state: artifacts, decisions, unresolved items.
+ - Slot-filling: inventing next steps or open questions because the template has a heading for them.
+ An omitted section can be a correct answer.
+
## When to Use
- Handing off work to a new conversation or agent.
- Resetting context while preserving execution continuity.
- Transferring partially complete implementation/debugging work.
+ - Transferring ideation, research, or writing context that lives only in the conversation.
- Capturing next actions before ending a session.
## When Not to Use
- Simple same-thread progress updates.
- Creating long-lived project documentation.
- Retrospectives not intended for immediate continuation.
## Workflow
1. Extract the objective, success criteria, and current status from available context.
2. Collect concrete evidence: files touched, commands run, validation status, blockers, and risks.
- 3. Capture decisions with rationale so the recipient understands intent and tradeoffs.
- 4. Fill every section of `assets/handoff-template.md`.
- 5. Ensure next steps are ordered and step 1 is immediately executable.
- 6. Return the completed template in chat for copy/paste.
-
- ## Output Rules
-
- - Match the template section headings exactly.
- - Keep statements specific and verifiable; avoid vague summaries.
- - Include validation details (passed, failed, or not run).
- - Include blockers with owner/dependency and concrete impact.
+ - Include references that shaped the work — files read, URLs, specs, prior artifacts — not only files edited; give each a one-line note on what it holds and why the recipient needs it.
+ - When a claim concerns repository state, verify it against the current working tree (`git status`, `git log`, `git diff --stat`) instead of conversation memory; the conversation's picture of the repo drifts over a long session.
+ - Derive the Changes Made list from the diff itself (`git diff --stat`, plus `--cached` for staged work) and reconcile every changed file and notable hunk against it; conversation memory under-reports.
+ - Report validation results only for checks run in this session; mark everything else as not run.
+ - When the handoff content is conversational (ideation, decisions, drafts), the conversation itself is the source; skip repo verification.
+ 3. Synthesize conversation-only content — decisions with rationale, user guidance, constraints, direction on drafts — so the recipient understands intent and tradeoffs.
+ - Write it as a briefing for a new colleague: distill substance and intent; do not transcribe the conversation.
+ - Quote exact wording only when the wording itself carries the value (user-authored text, names, error messages).
+ 4. Determine continuation strictly:
+ - Include only direction the user gave and the incomplete remainder of requested work.
+ - If no continuation was established, ideate with the user what the next session should do before writing the handoff.
+ - If the user gives no direction, omit the Continuation section; the startup prompt then tells the recipient to confirm direction with the user.
+ 5. Fill every applicable section of `assets/handoff-template.md`; omit sections that do not apply per the template's markers.
+ 6. When a Continuation section exists, order its items and make item 1 immediately executable.
+ 7. Return the completed template in chat for copy/paste.
## Quality Checklist
+ - Section headings match the template exactly; repo-only and only-if-established sections are omitted when they do not apply.
- The goal and definition of done are explicit.
+ - Sections agree with each other; the Goal and Status lines do not contradict Pending or Validation.
- Done vs. pending work is unambiguous.
- - Blockers include dependency/owner and impact.
- - Validation status includes what passed, failed, or was skipped.
- - The first next step can be executed immediately.
- - The recipient can proceed without asking for missing context.
+ - Every open obligation appears in Pending or Continuation, not in a note or footnote.
+ - Every Continuation item traces to user direction or the remainder of requested work; no invented work.
+ - Changes Made covers every file in the diff; no change is omitted because it was forgotten.
+ - References list only sources actually consulted, each with why it matters; no padding with plausible links.
+ - Statements are specific and verifiable; no vague summaries.
+ - Validation status includes what passed, failed, or was not run (when checks apply).
+ - Blockers include dependency/owner and concrete impact.
+ - When a Continuation section exists, its first item can be executed immediately.
+ - A continuation item that runs a check names its expected result and what to do if it fails.
+ - Command results stay on one line with inline code; no fenced code blocks nested inside the template's outer fence.
+ - The recipient can proceed, or knows exactly what to ask the user, without reconstructing lost context.
## References
- `assets/handoff-template.md` - canonical output format.