davepoon/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:

# 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:

# <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:

{
  "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 [email protected] \
          commit --quiet -m "session: <slug>" 2>/dev/null || \
      (sleep 1 && git -C ~/.origin add -A && \
       git -C ~/.origin -c user.name=Origin -c [email protected] \
           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.