Session Retro

---
name: session-retro
description: セッション振り返りによる指示ファイルの自律改善。現在のセッションで得た知見（ユーザーからの訂正・Claudeの間違い・発見した環境やPJ固有の落とし穴・繰り返された手動指示）を洗い出し、user-level（AGENTS.md）/project-level（CLAUDE.md）・context・スキルへの追加・修正を自律的に適用して報告する。「このセッションの学びを反映して」「振り返って指示を改善して」等の依頼時、/session-retro実行時、タスク完了時に知見の恒久化を求められた際に使用。境界: ユーザーが特定した単一の間違いの修正（承認付き）→update-inst、セッション内容によらないファイル品質の静的監査→instructions-audit、セッションの引き継ぎ文書化→handoff。
---

# Session Retro

現在のセッションを振り返り、指示ファイルに恒久化すべき知見を抽出して、自律的に適用・報告する。update-instの自律バッチ版（項目単位のユーザー承認を取らない代わりに、適用範囲を「追加・明確化」に限定する）。

## 既存設定との関係

- **記述・配置の原則**: @context/claude-customization-guide.md に従う（§1 置き場所判定、§3 書き方・保守、§4 skills設計）。本スキルに原則を重複記載しない
- **Phase 0-5（@context/workflow-rules.md）**: 独立。複雑タスクの完了後に実行した場合は05_log.mdに実行記録を残す

## ワークフロー

### Step 1: セッション走査（候補の収集）

会話全体を振り返り、以下のカテゴリで候補を列挙する:

| カテゴリ | 例 |
|---|---|
| ユーザーからの訂正・注意・好みの表明 | 「それは○○にして」「今後は△△で」 |
| Claudeの間違いと、その修正 | 指示があれば防げた誤り（誤ったコマンド・規約違反・誤発火） |
| 発見した非自明な事実 | 環境のクセ・コマンドの落とし穴・仕様の実挙動（推測が原文確認で覆った点を含む） |
| 繰り返された手動指示 | 2回以上ユーザーが同じ指示をした事項 |
| スキルのギャップ | 発火漏れ・誤発火・手順の不足・descriptionの弱さ |
| レビューで却下した指摘とその理由 | 05_log.mdのスキップ記録・同型却下の反復（配置先はPJ CLAUDE.md「レビュー方針」の却下類型。@context/agent-cli-guide.md「却下の蓄積を規約に還元する」） |

- 完了基準: 各候補に「セッション内の根拠（何が起きたか）」が1行で紐づいている

### Step 2: フィルタ（恒久化すべきものだけ残す）

各候補に以下を適用し、通らないものを落とす:

1. **実インシデント紐付け**: このセッションで実際に起きたこと・確認したことか（仮想のルールは足さない）
2. **no-opテスト**: この行はClaudeのデフォルト挙動を変えるか（変えないなら不要）
3. **重複チェック**: 追記先候補の指示ファイル（user-level実体はAGENTS.md、PJ-levelはCLAUDE.md）・context・スキルをGrep/Readし、既に書かれていないか確認。既存記述の不足が原因なら「追加」でなく「明確化」として扱う
4. **恒久性**: 今回のタスク限りの情報はメモリディレクトリ（05_log.md/99_history.md）行きであり、指示ファイルに入れない

**書き方（CRITICAL）**: 通過した項目は**一般化した規則としてのみ**書く。インシデントは規則を導く根拠であって、書く内容ではない。「実例: <PJ名>で〜が起きた」「（2026-07 実測）」の形で出来事・日付・固有名詞を指示ファイルに残さない（`~/.claude` は公開リポジトリ。詳細は AGENTS.md「指示ファイルの書き方」）。インシデント自体の記録が必要ならメモリディレクトリに書く。

- 完了基準: 残った各項目に「どのフィルタを通過したか」が確認済みで、落とした候補は理由付きでリスト化されている。かつ**追記した文面に出来事・日付・固有名詞が含まれていない**

### Step 3: 配置判定と適用

残った項目ごとに:

1. **配置先の決定**: @context/claude-customization-guide.md §1の判定表（CLAUDE.md/skill/context/hook）と§3のスコープ配置（user-level=全PJ共通、project-level=PJ固有）に従う
2. **適用**: ファイル編集ツール（Claude Code: Edit/Write）で反映する。user-level 指示の編集対象は `~/.claude/AGENTS.md`（実体。`CLAUDE.md` は互換symlink）。修正タイプ（追加/明確化/例示修正/優先度明示）と記述原則はguide §3に従う
3. **新規スキルが必要な場合**: `/create-skill` スキルを実行する（本スキル内で簡易作成しない）

**自律適用の範囲（IMPORTANT）**: 自律的に適用してよいのは「追加」と「既存指示の明確化」のみ。以下は適用せず、Step 4で提案として提示する（既存の合意を壊すリスクがあり、ユーザーの判断が必要なため）:
- 既存ルールの削除・弱体化・例外追加
- 既存指示と矛盾する変更
- settings.json（permissions/hooks）の変更
- ユーザーの好みの推測に基づく変更（表明が明確でないもの）

- 完了基準: 全項目が「適用済み」か「提案送り」のどちらかに分類され、適用済み項目は編集が完了している

### Step 4: 報告

以下の構成で報告する:

1. **適用した変更**: ファイル / 変更内容の要約 / 根拠となったセッション内の出来事（1行）
2. **提案（未適用）**: 自律適用の範囲外だった項目と、その理由・推奨案
3. **落とした候補**: フィルタで除外した候補と理由（1行ずつ。ユーザーが拾い直せるように）

- 完了基準: ユーザーが各変更をgit diffで確認でき、提案にyes/noで答えられる状態になっている

## Gotchas

- **user-level（`~/.claude/`）への適用時**: 変更後に `/commit --push` でコミットとpushまで行う（3PC間で同期しているため、変更を手元に残さない）
- **project-levelの`.claude/`・CLAUDE.mdへの適用時**: 実装開始前ゲートの「直コミット可否の判定」（@context/workflow-rules.md）に従う（チーム開発リポジトリなら作業ブランチで行う）
- **セッションが長い場合**: 走査はconversation全体を対象にする。compaction済みで詳細が失われている場合は、05_log.mdと要約から復元できる範囲で行い、その旨を報告に明記する
- **候補ゼロは正常**: 無理に変更を作らない。「恒久化すべき知見なし」と報告して終了する（変更を出すことが目的ではない）