diff --git a/projects/ai/artifacts/handoff-skill.md b/projects/ai/artifacts/handoff-skill.md new file mode 100644 index 0000000..f39d2b1 --- /dev/null +++ b/projects/ai/artifacts/handoff-skill.md @@ -0,0 +1,120 @@ +# /handoff skill for Claude Code + +## My take + +Good idea. Rationale: + +- The handoff brief is the cheapest reliable carrier of context between + sessions, but it is written at the exact moment nobody wants to write it: + at a session boundary, from a bloated context, by hand. +- A skill turns it into one word: `/handoff`. The effort argument against + "transfer via artifacts" disappears. +- Skills follow the Agent Skills open standard (agentskills.io), so the same + SKILL.md works in Codex and other tools with a compatible loader. +- One important design decision: the brief must be written **for the next + agent as the reader**, not as a human retrospective. That changes the + content: no narrative, no chronology — just state, decisions, and + constraints, in an order optimized for cold-context consumption. + +## Installation + +Pick a location by scope: + +| Scope | Path | +|---|---| +| Personal (all your projects) | `~/.claude/skills/handoff/SKILL.md` | +| One repo (shareable, commit it) | `/.claude/skills/handoff/SKILL.md` | + +(`.claude/commands/handoff.md` is the older format and still works, but +skills are preferred for new work.) + +Invoke with `/handoff`. Optionally pass the target filename as an argument +(e.g. `/handoff HANDOFF.md`); default is `HANDOFF.md` in the repo root. + +## SKILL.md content + +```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. Side-effect: writes + a file. Not for use mid-task. +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. + +## 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. + +## 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. Ask the user for the output path if not given; default HANDOFF.md in + the repo root. +2. Draft the brief per the structure above. +3. Show the draft to the user for review. Explicitly point out anything + you were unsure about (rule 5) so the review is fast. +4. On approval, write the file and confirm the path. Suggest a fresh + session prompt: "Read . Task: . Done when: ." +``` + +## Notes / tradeoffs + +- `disable-model-invocation: true` keeps it manual — a brief is a session + boundary action, and auto-triggering mid-task would produce noise. +- 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 diff --git a/projects/ai/memory.md b/projects/ai/memory.md index 6507e2c..7584ced 100644 --- a/projects/ai/memory.md +++ b/projects/ai/memory.md @@ -40,3 +40,6 @@ Shoda napříč zdroji: nová session při novém úkolu, review ve fresh contex 2. „Přenos = artefakty" konkretizace: 3 druhy — repo/diff (hlavní, nese celý stav implementace, nic přenášet nemusím), spec/plan soubor (při plánování), handoff brief (jen na hranici session: rozhodnutí + vyloučené cesty — to nejsou vidět v kódu). Brief píše MODEL na jednu žádost, já jen 30s review — moje práce jedna věta. Trvalé části odtékají do store, které stejně vedu (rozhodnutí → memory.md, opakovaná chyba → CLAUDE.md/AGENTS.md). Nepřenášet: historii chatu, retrospektivy, duplicity kódu. Draft uložen: projects/ai/artifacts/session-lifecycle-draft.md. Otevřená otázka: hranice „related task" (dokumentace k hotové feature — Anthropic nechává intuici). +- 2026-09-10: Nápad uživatele: /handoff skill pro Claude Code, který sepíše handoff brief pro dalšího agenta. Zhodnoceno jako dobrý (odstraňuje hlavní argument proti „přenos artefakty" — práci navíc na hranici session) a připraven jako artefakt: projects/ai/artifacts/handoff-skill.md (anglicky, instalační cesty personal/project, SKILL.md obsah v markdown fence). + +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.