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: >
+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.
-  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.
 disable-model-invocation: true
 ---
 
 # Handoff
 
-Write a brief that transfers this session's working context to another AI
+Render this session's context as one fenced markdown block, ready to copy
-agent that starts with ZERO conversation history. The reader will have the
+into a fresh session. The reader has the repo but no conversation history,
-repo and this file — nothing else.
+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
+```markdown
-
+# Handoff: <task in one line>
-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.
 
 ## 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
+- Output stays in chat by default; saving to a file is outside the skill
-  that nobody reads later is clutter. File only on explicit request —
+  (ask for it ad hoc). The brief is disposable. Anything durable belongs
-  the user decides whether the receiving side reads it via path or paste.
+  in existing stores: recurring mistake → CLAUDE.md/AGENTS.md, project
-- The 30-second user review stays in the loop on purpose: the model writes
+  decision → project memory/decision log.
-  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.

projects/ai/memory.md

@@ -44,3 +44,4 @@ Draft uložen: projects/ai/artifacts/session-lifecycle-draft.md. Otevřená otá
 
 Klíčová designová rozhodnutí: (1) brief je psaný pro čtenáře-agenta se ZERO historií — ne retrospektiva pro člověka: žádná chronologie ani narativ, jen stav+rozhodnutí+vyloučené cesty; neduplikovat repo (reader si přečte kód/diff); nejcennější sekce „Ruled out" — brání dalšímu agentovi chodit do mrtvých endů. (2) disable-model-invocation: true — session boundary akce, ne auto-trigger. (3) user zůstává v loopě jako fact-checker (model píše brief z plného, tedy degradovaného kontextu — rule 5: „if not sure it was decided, mark as open"). (4) Brief je jednorázový; trvalé části odtékají do CLAUDE.md/AGENTS.md/decision logu. Skills = Agent Skills open standard (agentskills.io), takže stejné SKILL.md funguje i v Codexu.
 - 2026-09-10: Úprava /handoff skillu po review uživatele: default output je markdown blok v chatu ke zkopírování, NE soubor. Soubor jen na explicitní požádání (default HANDOFF.md v repo root). Důvod: brief je jednorázový, soubor bez čtenáře je clutter; navíc paste funguje i tam, kde target agent nemá přístup k souboru (jiný stroj, jiný nástroj). Upravena description (bez "side-effect: writes a file"), Procedure (render do chatu → unsurity callout → file jen on request → navrh fresh prompt) a Notes/tradeoffs.
+- 2026-09-10: Zjednodušení /handoff skillu na návrh uživatele: 3x kratší verze (jeden akapát pravidel + samotná kostra šablony v fenced markdown bloku, bez Rules/Procedure sekcí). Co zůstalo: co psát (jen to, co repo neukazuje), co nepsat (chronologie, kód, narativ), (unverified) markery, kostra sekcí. Co vypadlo: Goal sekce (redundantní s titulkem), per-section vysvětlení, review procedura jako proces (nahrazeno (unverified) inline), file-save flow. Souhlasím — původní verze vysvětlovala věci, které model umí implikovat z šablony. Lessons: skill = šablona + constrainty, ne tréninkový dokument; iterovat přidáváním řádků po reálných selháních, ne upfront.