nanobot: 2026-09-10 12:57:24

projects/ai/artifacts/handoff-skill.md

@@ -37,90 +37,41 @@ in the repo root (or a path you give).
 ```markdown
 ---
 name: handoff
-description: >
-  Write a handoff brief that lets a fresh session (or a different agent)
-  continue this work without this session's conversation history. Run
-  manually when wrapping up a task or before /clear. Output is a markdown
-  block in the chat, ready to copy-paste; writes a file only if the user
-  asks. Not for use mid-task.
+description: Format this session's key context as a copy-pasteable handoff brief for a fresh session or another agent. Use when the user asks for a handoff, wants to carry context over, or is about to /clear, compact or restart.
 disable-model-invocation: true
 ---
 
 # Handoff
 
-Write a brief that transfers this session's working context to another AI
-agent that starts with ZERO conversation history. The reader will have the
-repo and this file — nothing else.
+Render this session's context as one fenced markdown block, ready to copy
+into a fresh session. The reader has the repo but no conversation history,
+so write only what the repo does not show: decisions and their reasons,
+what was ruled out and why, constraints the user set, what is left.
+No chronology, no code, no narrative. Omit empty sections. Mark anything
+you are not sure about with `(unverified)`.
 
-## Rules
-
-1. **Do not duplicate the repo.** The reader can read code, diffs, and file
-   trees. State what exists only where it matters (file paths as entry
-   points), never paste code or file contents.
-2. **Write what is NOT visible in the repo**: decisions and their reasons,
-   rejected approaches and their reasons, constraints from the user,
-   open questions. If a decision is recorded in a committed doc, reference
-   the doc in one line instead of restating it.
-3. **No chronology, no narrative, no reflection.** State facts for a cold
-   reader. "We tried X then Y" is wrong; "X and Y are ruled out (reason)"
-   is right.
-4. **Be specific, not complete.** A brief that lists everything real says
-   nothing. Include only what changes the reader's behavior.
-5. You are writing from a full (possibly degraded) context. Be conservative:
-   if you are not sure something was actually decided, mark it as open,
-   do not present it as fact.
-
-## Structure (omit a section if empty; keep this order)
-
-# Handoff: <one-line task description>
-
-## Goal
-What this work is for. 1–2 sentences.
+```markdown
+# Handoff: <task in one line>
 
 ## Current state
-What is done and verified. Reference files/paths as entry points.
-If verification is partial, say exactly which part is unverified.
-
 ## Constraints
-Hard rules from the user (style, architecture, scope, "do not" rules).
-
 ## Decisions
-- <decision> — <why>. One bullet per decision.
-
 ## Ruled out
-- <approach> — <why it failed or was rejected>. This section is the most
-  valuable one: it prevents the next agent from re-walking dead ends.
-
 ## Next step
-The single most useful action for the reader, with enough precision to
-start without re-deriving the plan.
-
 ## Done when
-Verifiable completion condition(s).
-
-## Procedure
-
-1. Draft the brief per the structure above and render it as a single
-   fenced markdown block in the chat, ready to copy-paste.
-2. Explicitly point out anything you were unsure about (rule 5) so review
-   is fast.
-3. Only if the user asks, save the brief to a file — default HANDOFF.md
-   in the repo root (or the path they give) — and confirm the path.
-4. Suggest a fresh session prompt: "Read <path or pasted brief>. Task:
-   <goal>. Done when: <done-when>."
+```
 ```
 
 ## Notes / tradeoffs
 
+- First draft was 3× longer (rules, per-section explanations, a review
+  procedure, file-save flow). Simplified after review: `(unverified)`
+  inline markers replace the separate review-callout procedure, and
+  everything that was merely obvious or speculative got cut — iterate
+  by adding lines only after real failures, not upfront.
 - `disable-model-invocation: true` keeps it manual — a brief is a session
   boundary action, and auto-triggering mid-task would produce noise.
-- Default output is chat, not a file: the brief is disposable, and a file
-  that nobody reads later is clutter. File only on explicit request —
-  the user decides whether the receiving side reads it via path or paste.
-- The 30-second user review stays in the loop on purpose: the model writes
-  the brief at its weakest point (full context), so the human is the
-  fact-checker, not the writer.
-- The brief is disposable. Anything durable belongs in existing stores:
-  recurring mistake → CLAUDE.md/AGENTS.md, project decision → project
-  memory/decision log. Handoff carries it across the session boundary;
-  it is not an archive.
+- Output stays in chat by default; saving to a file is outside the skill
+  (ask for it ad hoc). The brief is disposable. Anything durable belongs
+  in existing stores: recurring mistake → CLAUDE.md/AGENTS.md, project
+  decision → project memory/decision log.