--- name: handoff description: Write a session handoff diary to $HOME/tmp/handoff--.md so the next chat (zero context) can pick the work up exactly where this one left off — task, done, stuck, next step, pitfalls. --- # Handoff — session diary for cross-session memory An AI's memory ends with the session; the project lives for weeks. This skill closes that gap with one Markdown file. When invoked, write (or refresh) a handoff file so a brand-new chat with **zero context** can resume the work without the user re-explaining anything. Next session, the user's first message will be *"Read first"* — so this file is the only bridge. Write it for a reader who has never seen this conversation. ## Target file Path: `$HOME/tmp/handoff--.md` - **``** — a short kebab-case slug for the task/thread (e.g. `payment-retry`, `search-ranking`, `deploy-flow`). Derive it from the active ticket/task or the work at hand; if the user passed a name as an argument, use that. Keep the slug **stable** across days so a multi-day task's handoffs are greppable as a set. - **``** — today's date. Get it from the shell: `date +%y%m%d` (don't guess). - Example: `$HOME/tmp/handoff-payment-retry-260708.md`. `$HOME/tmp/` is the repo scratch dir (not shared/committed) — the right home for a personal working diary. Do not put handoffs under version control. ### Continuing a multi-day task Before writing, look for prior handoffs of the same task: ``` ls -t $HOME/tmp/handoff--*.md 2>/dev/null | head ``` If one exists, **read the most recent** and carry its content forward (see "Living document"), then write today's dated file. This keeps §2 (Done) and §5 (Pitfalls) accumulating instead of resetting each day. ## Steps ### 1. Gather concrete state (don't rely on memory alone) ``` cd /rd && git branch --show-current cd /rd && git log --oneline -15 cd /rd && git status -s cd /rd && git diff --stat date +%y%m%d ``` Also pull in: the active ticket(s) (Linear/Jira id + URL), any plan doc paths, and the key files/functions touched this session (with `file:line` anchors). Verify claims against the repo rather than trusting recollection — a handoff with a wrong path is worse than none. ### 2. Write the five sections The file must contain exactly these, in this order. Be concrete and specific — names, paths, commands, ticket ids — never vague ("did some refactoring"). A stranger must be able to act on it. ```markdown # HANDOFF: _Updated: · branch: `` · ticket: _ _New session: read this file first, then continue._ ## 1. Task — what we're working on The goal in 2–4 sentences. Why it matters, the ticket/plan links, the definition of done. ## 2. Done — what's already finished Bullet list of concrete, verifiable progress: commits (sha + subject), files/functions changed (`path:line`), decisions made. Only things actually finished. ## 3. Stuck / current state — where we are now The exact current state: what's half-done, what's failing, the last thing tried and its result, any uncommitted work in the tree. If blocked, name the blocker precisely (error text, missing data, waiting on whom). ## 4. Next step — the plan The concrete next action(s), in order. First step should be runnable immediately. Include the commands / files to touch and how to know it worked. ## 5. Pitfalls — never step on these again Hard-won lessons from THIS work: things that wasted time, wrong turns, environment quirks, "looks right but isn't" traps. Each as an imperative ("Don't X — it does Y; do Z instead"). Cumulative — keep prior valid pitfalls. ``` Match the user's working language; identifiers, paths, commands and ticket ids stay as they are. ### 3. Living document — carry forward & prune When a prior handoff for the same `` exists, build today's file from it: - Move finished items from §3/§4 into §2 (Done). - Rewrite §3 to the **current** state — delete stale "we're stuck on X" once X is resolved. - Replace §4 with the new next step. - §5 (Pitfalls) is append-mostly: keep every still-relevant pitfall, drop only ones made obsolete by a design change. Never turn it into a changelog ("removed on …") — current wisdom only. - Refresh the `_Updated:_` line. ### 4. Report Tell the user the exact file path and a one-line summary of the next step it records. Remind them (once) that the next session should start with *"Read `` first"*. ## Rules - Write for **zero context** — no "as we discussed", no unexplained pronouns, no reliance on conversation memory. Every reference resolves from the file + repo alone. - **Verify before writing** — anchor paths/commits/ticket ids against the actual repo; a confident wrong pointer sends the next session down a rabbit hole. - This skill **writes the handoff file only** — it does not commit, push, or change code. - Keep it tight. A handoff nobody reads because it's 500 lines is a failed handoff.