handoff

# /handoff End-of-session debrief. Three artifacts each pass: 1. **Granular MCP captures** — one per decision/lesson/gotcha (DB authoritative). 2. **Session log md** — narrative thread at `~/.origin/sessions/<YYYY-MM-DD-HHmm>-<slug>.md`. 3. **Project status md + json** — current goals + last-handoff timestamp at `~/.origin/sessions/_status/`. These are orthogonal: captures are queryable atoms, session log is the narrative thread, status file lets the next session see where we left off. ## Steps ### 1. Detect project + last handoff time ``` Bash: cd_repo=$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null); echo "${cd_repo:-no-git}" ``` - If output is a path → use the basename as `<project>` (e.g. `origin`). - If `no-git` → use the cwd basename. Skip git steps below; rely entirely on conversation context. Read `~/.origin/sessions/_status/handoff-<project>.json` for `lastHandoff` timestamp (ISO-8601). If file missing, default to "12 hours ago". ### 1.5 Pending-captures preview After establishing `<lastHandoff>`, call: ``` list_pending(limit=50) ``` The MCP returns memory rows with `source_id`, `content`, `created_at`, and other metadata. Convert `lastHandoff` (ISO-8601 string, e.g. `2026-05-13T22:50:00Z`) to a Unix epoch seconds integer before filtering: ``` Bash: date -j -f %Y-%m-%dT%H:%M:%SZ "$lastHandoff" +%s ``` Or in your scripting language of choice (Python's `datetime.fromisoformat`, JavaScript's `Date.parse`, etc.). Save the result as `lastHandoffEpoch`. Then filter the response rows: keep where `row.created_at >= lastHandoffEpoch`. These are captures this session produced that the quality gate left unconfirmed (untrusted-source captures). If the filtered list is empty, say nothing. Proceed to Step 2. If non-empty, render a preview block once, before the existing capture flow: ``` Pending captures this session (<N> total, top 3 shown): 1. mem_xyz789 "..." (untrusted source: <agent>) 2. ... Default: proceed (captures stay pending). Opt in by running `/review captures` before re-invoking /handoff if you want to walk them. ``` Do NOT prompt for per-item action inline. The user proceeds with /handoff regardless; the preview is informational only. ### 2. Gather session context (parallel, only if git repo) ``` Bash: git -C <repo> log --oneline --since=<lastHandoff> Bash: git -C <repo> status --short Bash: git -C <repo> diff --stat HEAD~5..HEAD 2>/dev/null Bash: git -C <repo> worktree list ``` Capture output. Use it alongside conversation history to infer what happened. If not a git repo, skip — conversation context is the source. ### 3. Infer, do not ask Synthesize silently from git output + conversation. Categorize each item into user-facing groups. Each maps to a daemon `memory_type` for the capture call: | Display label | daemon memory_type | What belongs here | |---|---|---| | Decisions | `decision` | architectural choice, tool/pattern selection (with WHY) | | Lessons | `lesson` | root cause discovered, workaround found, technical insight | | Insights | `gotcha` | unexpected behavior, debugging discovery, sharp edge | | Corrections | `preference` | user pushed back, corrected approach or assumption | | Facts | `fact` | durable project/people/tool fact worth persisting | Non-memory items (not stored, session-log only): - **Open threads** — started but not finished, blockers. Skip purely mechanical facts already in git (file paths, function names, config values). The commit log preserves those. ### 4. MCP captures (one per item) For each non-trivial item, call with the mapped `memory_type`: ``` capture(content="<one self-contained sentence with WHY>", memory_type="<decision|lesson|gotcha|preference|fact>") ``` Atomic: one decision per call. Don't merge multiple items into one memory. The daemon dedups against existing knowledge, so re-storing known facts is a no-op. Only surface items to the user BEFORE storing if they meet one of these bars: - Contradicts an existing memory (recall returned a conflicting fact). - Marks a critical incident, irreversible action, or production change. - You are uncertain whether the item is durable vs transient. Otherwise just store and report counts at the end. ### 5. Write session log Bash heredoc to `~/.origin/sessions/<YYYY-MM-DD-HHmm>-<slug>.md`: ```markdown # Session <YYYY-MM-DD HH:MM> — <slug> **Project:** <project> **Range:** <lastHandoff> → <now> ## Accomplished - <item> ## Decisions - <decision and rationale> ## Lessons & Gotchas - <root cause / workaround> ## Open Threads - <what's unfinished> ## Captures stored - <source_id_or_brief_summary> ## Git summary <git log --oneline output> ``` `<slug>` = kebab-case 2-4 word summary (`session-handoff-md-writer`). ### 6. Update project status Overwrite `~/.origin/sessions/_status/<project>.md`: ```markdown # <Project> — Current Status ## Last session (<date>) - <accomplished bullet> ## Active <!-- Items touched/spawned in the last 1-2 sessions. Real next-move candidates. --> - <item> (added <YYYY-MM-DD>) - <blocked item> (added <YYYY-MM-DD>) (gated: <trigger>) ## Backlog <!-- Older accretion. Not gated, not picked. Promote back to Active when re-engaged. --> - <item> (added <YYYY-MM-DD>) ``` Single file per project. New session overwrites — this is the *current* state, not a log. **Two sections, not one flat list:** `## Active` and `## Backlog` separate the two types of tasks that get mixed otherwise. Active = fresh signal worth picking next. Backlog = older parked items, kept for reference but not in the "what next?" frame. **Date stamp every bullet** with `(added <YYYY-MM-DD>)`. Use today's date when adding a new item; preserve the original date when carrying an item forward. Dates make age visible at a glance and avoid relative-time drift. **Gated items stay inline-tagged** with `(gated: <trigger>)` — no separate section. The tag tells the reader why it can't move yet; the bullet stays in whichever section reflects its recency. **Promotion / demotion rules:** - New item this session → `## Active` with today's date - Item in `## Active` that wasn't touched this session AND wasn't touched the prior session → demote to `## Backlog` (keep original date) - Item in `## Backlog` that work resumed on → promote back to `## Active` (keep original date — staleness is a property of the work, not the bullet text) ### 7. Write timestamp Overwrite `~/.origin/sessions/_status/handoff-<project>.json`: ```json { "lastHandoff": "<ISO-8601 now>", "project": "<project>", "summary": "<one-line>" } ``` Per-project file prevents parallel sessions from clobbering each other. ### 8. Auto-commit ~/.origin/ After writing the files above, snapshot the change so the user can `git log` their memory's life timeline. Defensive — silent skip if `git` is missing or `~/.origin/` is not a repo yet. ``` Bash: git -C ~/.origin add -A && \ git -C ~/.origin -c user.name=Origin -c user.email=daemon@origin.local \ commit --quiet -m "session: <slug>" 2>/dev/null || \ (sleep 1 && git -C ~/.origin add -A && \ git -C ~/.origin -c user.name=Origin -c user.email=daemon@origin.local \ commit --quiet -m "session: <slug>" 2>/dev/null) || true ``` The retry handles index.lock races — the daemon may be writing to `~/.origin/` at the same moment (auto-commit from captures). One-second wait is enough for the daemon to release the lock. ### 9. Confirm Print one summary block with captures grouped by display label: ``` Handoff stored. Decisions: <N> (brief list) Lessons: <N> (brief list) Insights: <N> (brief list) Corrections: <N> (brief list) Facts: <N> (brief list) Session: ~/.origin/sessions/<filename> Status: ~/.origin/sessions/_status/<project>.md Git: <commit hash> session: <slug> ``` Show each label only if non-empty. List items as short phrases, not full sentences — the session log has the details. ## When to use - "Wrapping up", "let's call it", "we're done". - Session about to close and useful state would otherwise be lost. ## When NOT to use - Mid-flow capture during work → use `/capture` (single memory). - Search / lookup → use `/recall`. - One-off chat with no decisions or lessons — captures alone are enough. ## Notes on the three artifact classes - **Memories** (MCP captures) live in the daemon DB only. Confirmation flips a `stability` flag — they never get exported to md. - **Pages** are wiki-style syntheses written to `~/.origin/pages/` by the daemon when `/distill` runs. Citations link back to source memory ids. - **Sessions** (this skill) live only at `~/.origin/sessions/`. They are the narrative axis: chronological, not topical. Browse them as a changelog of your work.