Session Handoff
Create one compact, factual resume artifact for a fresh session. Optimize for
correct continuation, not for recording everything that happened.
Evidence first
- Identify the project the user intends to resume. If it is a repository,
inspect live branch, HEAD,
git status --short --branch, and the relevant
changed paths. Do not infer completion from a clean tree or from an agent's
prose.
- Read the authoritative task artifacts and the current conversation context.
Separate:
- verified state from commands or files;
- explicit user decisions and constraints;
- work reported but not independently verified;
- unresolved questions, failures, and same-root residuals.
- Record test evidence only when the exact command and result are available.
A focused green test is not a green full suite. Planned, started, or claimed
work is not completed work.
- Include conversation-only facts only when the next session cannot recover
them cheaply from repository files or history. Omit completed detours,
narration, and background that does not change the next action.
Git dirtiness can prove a code phase, but a clean tree cannot prove a design
phase. Determine design, code, or mixed state from both the task context and
live artifacts.
Actionable-state gate
If there is no active goal, decision, blocker, pending work, or non-recoverable
context, do not create .handoff/ or a handoff file. Say that there is no
actionable state to transfer and ask the user to invoke the skill in the
original session if context was lost.
Write the packet
When actionable state exists, create exactly one file at
.handoff/YYYY-MM-DD-HHMM-session.md inside the intended project. Use only the
sections that carry real continuation value:
# Resume
## Current state
- Goal: ...
- Working directory: ...
- Branch / HEAD: ...
- Worktree: ...
## Verified completed
- ...
## In progress and residuals
- ...
## Next action
- ...
## Decisions and constraints
- Selected: ... / Rejected: ... / Because: ...
## Verification
- `<exact command>` — PASS | FAIL | NOT RUN; scope: ...
## Relevant files
- `path` — why it matters
Rules:
- Omit empty sections. Never write
None or N/A.
- For a pure design handoff, verify repository state but omit working
directory, branch, HEAD, worktree, changed-file inventory, relevant-file
lists, and facts that merely say the repository exists or no implementation
has started. Include a code artifact or Git fact only when it directly
constrains the next design decision.
- Use one exact next action when the path is known. List alternatives only when
a real unresolved decision creates multiple valid branches; do not add a
generic options menu or ask the user to choose again.
- Preserve explicit rationale. If a decision's reason is unavailable, write
rationale not captured — verify before relying on it; never invent one.
- Mark unverified claims and incomplete evidence plainly.
- Keep file lists to paths that affect resumption. Do not dump the whole diff.
- Do not commit, push, modify product code, or change task state while creating
the packet.
After writing, report the absolute handoff path and one sentence naming the
captured next action.
1---2name: session-handoff3description: Use only when the user explicitly names session-handoff or explicitly asks to create a durable resume packet for a later agent session. Capture the exact live state, unresolved work, decisions, constraints, and next action needed to continue without re-deriving context; do not create a packet when there is no actionable state to transfer.4---56# Session Handoff78Create one compact, factual resume artifact for a fresh session. Optimize for9correct continuation, not for recording everything that happened.1011## Evidence first12131. Identify the project the user intends to resume. If it is a repository,14 inspect live branch, HEAD, `git status --short --branch`, and the relevant15 changed paths. Do not infer completion from a clean tree or from an agent's16 prose.172. Read the authoritative task artifacts and the current conversation context.18 Separate:19 - verified state from commands or files;20 - explicit user decisions and constraints;21 - work reported but not independently verified;22 - unresolved questions, failures, and same-root residuals.233. Record test evidence only when the exact command and result are available.24 A focused green test is not a green full suite. Planned, started, or claimed25 work is not completed work.264. Include conversation-only facts only when the next session cannot recover27 them cheaply from repository files or history. Omit completed detours,28 narration, and background that does not change the next action.2930Git dirtiness can prove a code phase, but a clean tree cannot prove a design31phase. Determine design, code, or mixed state from both the task context and32live artifacts.3334## Actionable-state gate3536If there is no active goal, decision, blocker, pending work, or non-recoverable37context, do not create `.handoff/` or a handoff file. Say that there is no38actionable state to transfer and ask the user to invoke the skill in the39original session if context was lost.4041## Write the packet4243When actionable state exists, create exactly one file at44`.handoff/YYYY-MM-DD-HHMM-session.md` inside the intended project. Use only the45sections that carry real continuation value:4647```markdown48# Resume4950## Current state51- Goal: ...52- Working directory: ...53- Branch / HEAD: ...54- Worktree: ...5556## Verified completed57- ...5859## In progress and residuals60- ...6162## Next action63- ...6465## Decisions and constraints66- Selected: ... / Rejected: ... / Because: ...6768## Verification69- `<exact command>` — PASS | FAIL | NOT RUN; scope: ...7071## Relevant files72- `path` — why it matters73```7475Rules:7677- Omit empty sections. Never write `None` or `N/A`.78- For a pure design handoff, verify repository state but omit working79 directory, branch, HEAD, worktree, changed-file inventory, relevant-file80 lists, and facts that merely say the repository exists or no implementation81 has started. Include a code artifact or Git fact only when it directly82 constrains the next design decision.83- Use one exact next action when the path is known. List alternatives only when84 a real unresolved decision creates multiple valid branches; do not add a85 generic options menu or ask the user to choose again.86- Preserve explicit rationale. If a decision's reason is unavailable, write87 `rationale not captured — verify before relying on it`; never invent one.88- Mark unverified claims and incomplete evidence plainly.89- Keep file lists to paths that affect resumption. Do not dump the whole diff.90- Do not commit, push, modify product code, or change task state while creating91 the packet.9293After writing, report the absolute handoff path and one sentence naming the94captured next action.
hburaktasyurek