save ยท diff

git:20261115.c3438cb to git:20261115.0326cb7

20 added, 51 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: save
- description: Use when the user asks to save this unfinished session for a fresh one. Not for a plan another executor runs (spec) or finished work.
+ description: "Writes a handoff file for unfinished work and reads it back in a fresh session. Use when the user asks to save, pause or hand off this session, or to continue from a saved handoff ('continue where I left off'). Not for finished work."
argument-hint: "[what the next session must not lose]"
---
- # Handoff
+ # Save
- Freeze what this session knows and the next one cannot rebuild. The enemy is a handoff that pastes the transcript back, so the fresh session pays again for the context the clear just bought. The overcorrection is a page of headlines naming no file, command or next step, leaving the reader to rediscover the work.
+ Freeze what this session knows and the next one cannot rebuild. Point to files and commands, never paste the transcript, a diff or a log, because the fresh session would pay again for that context.
## Before writing
- - Take no irreversible action to pause: no push, no pull request.
- - Pause between atomic steps, not inside one: complete or undo the step in progress and begin no new work.
- - On the run branch of a plan (`exo:build` loop), commit nothing. Write partial work of the task in progress to a hint file such as `.exo/carry/task<n>-partial.patch`, and list it under `## Progress`.
- - On a non-default branch that is not a plan run branch, commit every uncommitted edit first as one `chore: wip <topic>` commit.
- - If the tree is broken, say so in that commit's body.
- - On the default branch, leave edits uncommitted and list them under `## Progress`.
- - Preserve verbatim any artefact the user explicitly asked to survive the clear, such as a question list or checklist.
-
- ## Pointers, not content
-
- - Each section names a path, command, issue number or line range, and stops there.
- - Paste no diff, file body or log; the reader can open them.
- - For an error, paste only its failing lines.
- - Quote a value only when it exists nowhere on disk, such as a number from an unlogged run.
-
- ## Where it goes
-
- 1. Read the location instead of guessing it: `node "${CLAUDE_SKILL_DIR}/scripts/handoff.mjs" path` prints it.
- 2. A branch name holding `/` gives a nested path, so create parent directories first.
- 3. Write the file whole, replacing any handoff already at that path: the state it held is what this clear discards.
-
- ## What it holds
-
- Fill `assets/handoff-template.md` and keep its section order, with no chat history. The file is read by the user, so write plain words in the user's language per `../../lib/references/user-read-format.md`.
-
- The last line of the file is `Resume: <prompt>`, one sentence in the user's language telling a fresh session to read this handoff by the path `handoff.mjs path` printed and continue.
-
- In those sections:
-
- - When a plan is running with `<plan stem>-decisions.md` beside it, carry its lines into `## Progress` unchanged.
- - Put a claim no command proved under the unproven list in `## Evidence`, not the proven one.
- - Run `node "${CLAUDE_SKILL_DIR}/../../lib/ruled-out.mjs" show <n>` for the task in progress and carry its lines into `## Evidence` as approaches the next session must not retry.
- - List each correction the user made this session under `## Evidence`, with the one-line rule or check that would have prevented it.
- - Read `## Progress` from `git status --short`, not memory.
- - List which changes are committed, then every uncommitted path in full, because a next session that cannot see the difference treats working-tree edits as saved and discards them.
- - For a session running a plan, open `## Progress` with the plan path and the number of the task in progress.
-
- ## Resume
+ - Push nothing and open no pull request.
+ - Finish or undo the step in progress and start no new work.
+ - On a plan's run branch, commit nothing: save the partial work of the task in progress with `git diff > .exo/carry/task<n>-partial.patch` and list it under Progress.
+ - On any other non-default branch, commit every uncommitted edit as one `chore: wip <topic>` commit, and say in its body if the tree is broken.
+ - On the default branch, leave edits uncommitted and list them under Progress.
- Copy this paragraph into `## Resume` exactly, so the reading session inherits the rule without this skill:
+ ## Write the file
- ```text
- Diff the work this handoff records as done against the work it still lists as next or open, name the resume point, and repeat no step it records as proven. Verify an inherited claim against the real artifact before building on it: a prior session's report is not the proof. Compare the `Written` date and last commit with `git log -1` and `git status --short`, and name what changed since before relying on a claim.
- ```
+ 1. Run `node "${CLAUDE_SKILL_DIR}/scripts/handoff.mjs" path` for the location, create its parent directories, and write the file whole, replacing an older handoff.
+ 2. Write plain words in the user's language, with these sections in order:
+ - One line on where the work stands and the first thing to do next, then `Written: <date>, last commit <short hash>, branch <name>`.
+ - `## Goal`: what the work is for, and what it will not do.
+ - `## Progress`: from `git status --short`, not memory. Open with the plan path and task number when a plan runs. List what is committed, then every uncommitted path in full, because a next session that cannot tell them apart discards working-tree edits. Add each decision as "<decision>, decided by <the user or this session>".
+ - `## Evidence`: `Proven:` claim, command, result; `Unproven:` what is open and who can answer. Add each approach already ruled out.
+ - `## Next step`: the first action, then each later step with its full command. For a run, say how to wait, what to do on failure and where to stop.
+ - `## Resume`: copy this paragraph exactly: "Diff the work this handoff records as done against the work it still lists as next or open, name the resume point, and repeat no step it records as proven. Verify an inherited claim against the real artifact before building on it: a prior session's report is not the proof. Compare the `Written` date and last commit with `git log -1` and `git status --short`, and name what changed since before relying on a claim."
+ 3. End the turn by naming the written path and telling the user to run `/clear`, then say "continue from the handoff". Continue no work.
- ## References
+ ## Continue from a handoff
- | File | Read it when |
- |---|---|
- | `references/reconstructing-without-a-note.md` | Save-session itself starts without a note and must rebuild context before saving. |
+ When the user asks to continue saved work, run `node "${CLAUDE_SKILL_DIR}/scripts/handoff.mjs" path`, read the file it prints and follow its `## Resume` paragraph. With no file there, say which branch has none and write nothing.
## Judgment
- Confirm path, branch and commit with a command before writing them down.
- - A short true handoff outranks a full one that guesses.
- - Turn ends naming the written path, saying to run `/clear`, and quoting the `Resume:` prompt to paste after it. Nothing else written; no work continues after.