sw-handoff

Session Watcher Handoff

Prepare a handoff package so the next session can resume without re-reading what its first task needs, and without carrying what that task will not open.

Steps

1. Get turn skeleton via the get_turn_skeleton tool → { snapshot_id, skeleton_path, notes_path, protocol }. Follow the protocol sentence it returns; it states how the two files are filled.

   • The call fails — an error instead of that shape, whatever its cause. Stop this run: report to the user that the turn skeleton could not be captured; do not produce or submit notes, and do not go on to prepare_handoff.

2. Produce turn notes you MUST follow NOTES.md exactly for what each note says. Write them inline — do not delegate to a subagent.

3. Submit notes via the submit_turn_notes tool with snapshot_id. The tool reads notes_path itself.

   • invalid_notes — each issues entry names a t, and each one is one section of notes_path. Edit those sections and submit again, at most three times (four submissions in all). If the last one still rejects, stop and report to the user; do not loop.

   The other three codes stop this run. Report the error to the user and take no further step:

   • stale_snapshot — snapshot is no longer current. Stop: report to the user; do not re-fetch the skeleton or re-produce notes.
   • invalid_snapshot — the capture's source identity or required metadata is invalid, including a transcript that cannot be read. Stop: report to the user.
   • storage_unavailable (retryable: true) — store temporarily unavailable. Stop: report to the user; they may re-run the skill when ready.

4. Fetch bucket data via the get_bucket_summary tool.

   If metrics.br < 0.05 AND few turns: note "Context is still light — handoff may not be necessary yet, but proceeding as requested."

5. Select paths to keep. The kept set is what the next task must have in hand before it can act. Candidates are the bucket summary plus any path this segment used that the bucket lacks. For each candidate, name the act of next_task that opens it; a candidate with no such act is not kept, whatever this segment did with it.

   • The repo outlives the context reset and the conversation does not, so a file the next session can read on demand is kept only where that first act needs it in hand: the file the task edits, the test that guards it, the artifact under discussion.
   • A blob under review is read by its reviewer, so what the next task needs is the review's return and the sources it cites.
   • Read each candidate's tokens from the bucket summary and total them before prepare. Where one path carries more than half that total, state which act needs all of it, or keep its symbols alone.