handoff

/handoff

セッション終了時の振り返りです。毎回、次の3つの成果物を作成します。

1. 粒度の細かい MCP キャプチャ — 意思決定・教訓・注意点ごとに1件（DB が正）。
2. セッションログ md — ~/.origin/sessions/<YYYY-MM-DD-HHmm>-<slug>.md に記録する経緯。
3. プロジェクトステータス md + json — 現在の目標と最終ハンドオフ時刻を ~/.origin/sessions/_status/ に記録します。

これらはそれぞれ独立しています。キャプチャは検索可能な情報の単位、セッションログは経緯、ステータスファイルは次のセッションで前回の続きから始められるようにするものです。

手順

1. プロジェクトと最終ハンドオフ時刻を特定する

Bash: cd_repo=$(git -C "$PWD" rev-parse --show-toplevel 2>/dev/null); echo "${cd_repo:-no-git}"

• 出力がパスの場合は、ベース名を <project> として使用します（例：origin）。
• no-git の場合は、cwd のベース名を使用します。以下の git 手順はスキップし、会話のコンテキストだけを参照します。

~/.origin/sessions/_status/handoff-<project>.json を読み込み、lastHandoff のタイムスタンプ（ISO-8601）を取得します。ファイルがない場合は、デフォルトで「12時間前」とします。

1.5 未確定キャプチャのプレビュー

<lastHandoff> を確定した後、次を呼び出します。

list_pending(limit=50)

MCP は source_id、content、created_at などのメタデータを含むメモリー行を返します。フィルタリングの前に、lastHandoff（ISO-8601 文字列。例：2026-05-13T22:50:00Z）を Unix エポック秒の整数に変換します。

Bash: date -j -f %Y-%m-%dT%H:%M:%SZ "$lastHandoff" +%s

または、任意のスクリプト言語を使用します（Python の datetime.fromisoformat、JavaScript の Date.parse など）。結果は lastHandoffEpoch として保存します。

次に、応答行をフィルタリングし、row.created_at >= lastHandoffEpoch を満たす行を残します。これらは、品質ゲートで未確認のままになった、このセッションで作成されたキャプチャ（信頼されていないソースからのキャプチャ）です。

フィルタリング後のリストが空の場合は、何も言わずに手順2へ進みます。

空でない場合は、既存のキャプチャフローの前に、プレビューブロックを1回表示します。

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.

項目ごとの対応をインラインで促してはいけません。ユーザーは通常どおり /handoff を続行します。プレビューは情報提供のみを目的とします。

2. セッションのコンテキストを収集する（git リポジトリの場合のみ並行して実行）

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

出力を取得します。会話履歴と合わせて、何が起きたかを推測するために使用します。git リポジトリでない場合はスキップし、会話のコンテキストを情報源とします。

3. 質問せずに推測する

git の出力と会話から、黙って情報をまとめます。各項目をユーザー向けのグループに分類します。各グループは、キャプチャ呼び出しに使うデーモンの memory_type に対応します。

表示ラベル	デーモンの memory_type	該当する内容
決定事項	decision	アーキテクチャ上の選択、ツール／パターンの選定（理由を含む）
教訓	lesson	判明した根本原因、見つかった回避策、技術的な知見
洞察	gotcha	想定外の動作、デバッグで判明したこと、注意すべき落とし穴
修正事項	preference	ユーザーが異議を唱え、アプローチや前提を修正したこと
事実	fact	保存する価値のある、長期的に有用なプロジェクト／人物／ツールに関する事実

メモリーに含めない項目（保存せず、セッションログのみに記録）：

• 未解決の作業 — 着手したものの未完了の作業や、ブロッカー。

git にすでに記録されている、純粋に機械的な事実（ファイルパス、関数名、設定値など）はスキップします。これらはコミットログに残ります。

4. MCP キャプチャ（項目ごとに1件）

重要な項目ごとに、対応する memory_type を指定して呼び出します。

capture(content="<one self-contained sentence with WHY>", memory_type="<decision|lesson|gotcha|preference|fact>")

原子的に扱います。呼び出し1回につき意思決定は1つです。複数の項目を1つのメモリーにまとめてはいけません。デーモンは既存の知識と照合して重複を排除するため、既知の事実を再保存しても何も起きません。

次のいずれかに該当する場合のみ、保存する前に項目をユーザーに提示します。

• 既存のメモリーと矛盾する（リコールによって矛盾する事実が返された）。
• 重大なインシデント、取り消せない操作、本番環境の変更に関する内容である。
• その項目が長期的に有用か、一時的なものか判断できない。

それ以外はそのまま保存し、最後に件数を報告します。

5. セッションログを作成する

Bash のヒアドキュメントを使い、~/.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> は、内容を表す2〜4語のケバブケースにします（session-handoff-md-writer）。

6. プロジェクトのステータスを更新する

~/.origin/sessions/_status/<project>.md を上書きします。

# <Project> — Current Status

## Last session (<date>)
- <accomplished bullet>

## Active

- <item> (added <YYYY-MM-DD>)
- <blocked item> (added <YYYY-MM-DD>) (gated: <trigger>)

## Backlog

- <item> (added <YYYY-MM-DD>)

プロジェクトごとにファイルは1つです。新しいセッションで上書きされます。これはログではなく、現在の状態です。

フラットなリストではなく、2つのセクションに分けます： ## Active と ## Backlog で、混同されがちな2種類のタスクを分けます。Active は、次に取り組む候補として選ぶ価値のある、新しいシグナルです。Backlog は、古い保留中の項目を参照用に残すもので、「次に何をするか？」の候補には含めません。

すべての箇条書きに日付を付けます： (added <YYYY-MM-DD>)。新しい項目を追加するときは今日の日付を使い、項目を引き継ぐときは元の日付を維持します。日付があれば、項目の古さがひと目でわかり、相対時間のずれも防げます。

ゲート付きの項目は、インラインタグを付けたままにします： (gated: <trigger>) — 専用のセクションは作りません。このタグで、項目をまだ進められない理由を伝えます。箇条書きは、鮮度を反映するセクションに残します。

昇格／降格のルール：

• 今回のセッションでの新しい項目 → 今日の日付を付けて ## Active にする
• ## Active にある項目のうち、今回のセッションでも直前のセッションでも触れられなかったもの → 元の日付を維持して ## Backlog に降格する
• ## Backlog にある項目のうち、作業を再開したもの → 元の日付を維持して ## Active に昇格する（古さは作業そのものの性質であり、箇条書きのテキストの性質ではありません）

7. タイムスタンプを書き込む

~/.origin/sessions/_status/handoff-<project>.json を上書きします。

{
  "lastHandoff": "<ISO-8601 now>",
  "project": "<project>",
  "summary": "<one-line>"
}

プロジェクトごとにファイルを分けることで、並行するセッション同士が互いの内容を上書きしないようにします。

8. ~/.origin/ を自動コミットする

上記のファイルを書き込んだ後、変更をスナップショットとして記録します。ユーザーは git log で記憶の変遷をたどれます。防御的な処理として、git が見つからない場合や ~/.origin/ がまだリポジトリではない場合は、何もせずにスキップします。

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

リトライ処理は、index.lock の競合に対応します。デーモンが同時に ~/.origin/ に書き込んでいる可能性があります（キャプチャからの自動コミット）。1秒待てば、デーモンがロックを解放するには十分です。

9. 確認する

表示ラベルごとにキャプチャをまとめ、要約ブロックを1つ表示します。

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>

内容がある場合にのみ、各ラベルを表示します。項目は完全な文ではなく、短いフレーズで記載します。詳細はセッションログにあります。

使用する場面

• 「そろそろ終わりにしよう」「ここまでにしよう」「完了です」などの場合。
• セッションを閉じる前に、役立つ状態が失われるおそれがある場合。

使用しない場面

• 作業中の途中経過の記録 → /capture（単一の記憶）を使います。
• 検索／参照 → /recall を使います。
• 決定や教訓がない単発のチャット — キャプチャだけで十分です。

3種類の成果物に関する注意事項

• 記憶（MCP キャプチャ）はデーモンの DB 内にのみ保存されます。確認すると stability フラグが切り替わります。md にはエクスポートされません。
• ページは、/distill の実行時にデーモンが ~/.origin/pages/ に書き込む、Wiki 形式の統合情報です。引用は元の記憶 ID にリンクします。
• セッション（このスキル）は ~/.origin/sessions/ 内にのみ保存されます。セッションは物語の軸です。時系列順であり、トピック別ではありません。作業の変更履歴として閲覧してください。