reflect

フェーズゲート：COMMIT チェックポイント。Step 8 に合格するまで、タスク完了を宣言しないでください。

すべてのステップを順番に実行してください。明示されたエスカレーションポイントでのみ、ユーザーにエスカレーションしてください。

Step 0 — reflect のタイムスタンプを記録する

date +%s > "${CLAUDE_PROJECT_DIR}/ai-workspace/.last-reflect-ts"

Step 1 — セッションでの作業を確認する

git log --oneline -10

このセッション中に行われた最近の編集や修正を確認します。ai-workspace/plans/ に完了済みの計画（Outcomes & Learnings が記入済み）がある場合は、それを主要な情報源として使用します。ない場合は、git の履歴とセッション中のイベントから直接学びを導き出します。先に進む前に、候補となる学びを明示的に一覧にまとめます。

Step 1b — Issue の解決を確認する

コミットメッセージをスキャンし、クローズを示すキーワード（大文字と小文字を区別しない）を探します。対象は closes、close、closed、fixes、fix、fixed、resolves、resolve、resolved の後に #N が続くものです。

見つかった Issue 番号ごとに、次を実行します。

gh issue view N --json state --jq '.state'

参照されている Issue がまだオープンの場合は警告します。処理はブロックせず、警告後に続行してください。

Step 2 — 学びを分類する

シグナル	保存先
このリポジトリのファイル、パス、設定、またはプロジェクトの規約に関するもの	MEMORY.md のみ
プロジェクトをまたいで適用できる一般的なパターン、ツールの動作、または好みに関するもの	Basic Memory vault のみ
両方（プロジェクト固有の事例であり、プロジェクト横断的なパターンでもあるもの）	両方 — 各項目から相互に参照する

Step 2b — 関連する Issue に学びをコメントする

計画の frontmatter に Issue: #N がある場合：その Issue に直接、学びをコメントとして投稿します。リンクが明示されているため、確認は不要です。

計画がない場合、または Issue フィールドがない場合：gh issue list --state open --json number,title,labels --limit 50 を実行し、キーワードをオープン中の Issue のタイトルとあいまい一致させます。あいまい一致した Issue に投稿する前に、ユーザーに確認してください。誤った自動コメントは、コメントを見逃すよりも悪影響があります。

Step 3 — MEMORY.md に書き込む（同時書き込みプロトコル）

MEMORY.md は main ブランチにあり、同時に書き込みが行われる可能性があります。現在の作業ツリーから書き込まないでください。

REFLECT_DIR="${CLAUDE_SESSION_DIR:-$TMPDIR}/memory-reflect"
[ -d "$REFLECT_DIR" ] && rm -rf "$REFLECT_DIR"
git clone --depth 50 "$(git remote get-url origin)" "$REFLECT_DIR"

再試行ループ（最大 3 回）：

1. 現在の $REFLECT_DIR/ai-workspace/MEMORY.md を読み込みます。
2. 現在のファイルの状態から項目を再導出します。すでに存在するものはスキップし、重複を避けてください。自動マージはしないでください。古い差分を再適用しないでください。
3. 新しい項目を追加します。30 日を超える項目は整理します。200 行未満に保ちます。超える場合は、最も古いセクションを要約してください（黙って削除しないでください）。
4. コミットしてプッシュします。

git -C "$REFLECT_DIR" add ai-workspace/MEMORY.md
git -C "$REFLECT_DIR" commit -m "reflect: update MEMORY.md [$(date +%Y-%m-%d)]

Co-Authored-By: Claude <model>"
git -C "$REFLECT_DIR" push

5. fast-forward 以外の拒否が発生した場合：git -C "$REFLECT_DIR" pull --rebase を実行し、ステップ 1 に戻ります。
6. 3 回失敗した場合は停止してエスカレーションし、続行しないでください。

   3 回再試行しましたが、MEMORY.md の書き込みに失敗しました。$REFLECT_DIR/ai-workspace/MEMORY.md で手動マージが必要です。

プライマリ作業ツリーに反映する

プッシュに成功したら、プライマリ作業ツリーの main を最新の状態に更新し、ほかのエージェントが新しい MEMORY.md をすぐに確認できるようにします。

PRIMARY="$(git worktree list --porcelain | grep -m1 '^worktree ' | sed 's/^worktree //')"
CURRENT=$(git -C "$PRIMARY" branch --show-current)
if [ "$CURRENT" = "main" ]; then
  # WIP commit if dirty
  if [ -n "$(git -C "$PRIMARY" status --porcelain)" ]; then
    git -C "$PRIMARY" add -u
    git -C "$PRIMARY" commit -m "wip: preserve local state before reflect sync"
    WIP=1
  fi
  git -C "$PRIMARY" fetch origin main
  git -C "$PRIMARY" merge --ff-only origin/main || echo "Primary diverged — manual pull needed"
  # Restore WIP
  [ "${WIP:-}" = "1" ] && git -C "$PRIMARY" reset --soft HEAD~1
fi

プライマリ作業ツリーが main でない場合は、反映をスキップしてください。次の git pull で取り込まれます。

Step 4 — Basic Memory vault に書き込む

重複を避けるため、まず mcp__basic-memory__search_notes を使用し、次に mcp__basic-memory__write_note または mcp__basic-memory__edit_note を使用します。関連付けには [[wiki-links]] を使用します。すべてのノートに現在のプロジェクト名をタグ付けしてください。

Basic Memory MCP に接続されていない場合は、出力の要約にスキップしたことを記録し、続行してください。処理はブロックしないでください。

Step 5 — ADR の確認

重要なアーキテクチャ上の決定、規約、または繰り返し見られるパターンが見つかった場合は、次のように尋ねます。

これを ADR にしますか？候補：「<パターンの概要>」（y/n）

「はい」の場合：ai-workspace/decisions/TEMPLATE.md のテンプレートを使って ai-workspace/decisions/ADR-NNN-<slug>.md を作成します。既存の ADR の最大番号に 1 を加えます。

Step 6 — 表面化した作業から Issue を作成する

まず重複を確認します（オープン中および最近クローズされたもの）。

gh issue list --state open --limit 100 --json number,title
gh issue list --state closed --limit 20 --json number,title

ソース (a) — Reflect の TODO：Step 1〜5 で明らかになった注意点、フォローアップ、技術的負債。重複がないものについて、それぞれ GitHub Issue を作成します。

ソース (b) — スクラッチパッド（ai-workspace/scratchpad.md）：- [ ] ... に一致する各行について、Issue を作成し、- [x] → #N に書き換えます。通常の箇条書きは参照用メモなので、そのまま残します。

ステップ 7 — 計画を最終確定する

アクティブな計画の名前を .done.md に変更します。先に Outcomes & Learnings が記入されていることを確認してください。

mv ai-workspace/plans/<name>.md ai-workspace/plans/<name>.done.md

このコミットはプライマリワークツリーで行えます。.done.md の計画ファイルは許可リストに含まれています（task-branches.md を参照）。アクティブな計画がない場合はスキップしてください。

ステップ 8 — フェーズゲート

.branch-context.md を読みます。

• MEMORY.md が更新されていない + .branch-context.md に内容があった → ソフトブロック：警告を出し、解決するまでタスク完了を宣言しないでください。
• .branch-context.md が存在しない、または空である → 警告を出しますが、ブロックはしません。

出力の概要

レイヤー	アクション
MEMORY.md	N 件を追加、N 件を削除（合計 X 行）
Basic Memory	N 件のノートを記録／更新（または：スキップ — MCP は利用不可）
クローズした Issue	#N、#N（確認済み）／#N は未解決のまま（警告済み）
作成した Issue	#N「」、#N「<title>」
コメントした Issue	#N
ADR	ADR-NNN を作成／スキップ
計画	.done.md として最終確定／なし
フェーズゲート	MEMORY.md の更新：はい／いいえ — .branch-context.md：検出／未検出