diff --git a/projects/ai/artifacts/handoff-skill.md b/projects/ai/artifacts/handoff-skill.md index 5f62af3..330506b 100644 --- a/projects/ai/artifacts/handoff-skill.md +++ b/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: - -## Goal -What this work is for. 1–2 sentences. +```markdown +# Handoff: ## 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 -- — . One bullet per decision. - ## Ruled out -- — . 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 . Task: - . 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. \ No newline at end of file +- 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. \ No newline at end of file diff --git a/projects/ai/memory.md b/projects/ai/memory.md index 80f04a6..36d9dc9 100644 --- a/projects/ai/memory.md +++ b/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.