--- name: session-review description: > セッションの振り返りを実施するときに起動する。ユーザー手動起動、Stopフック、process-feedbacksの終了工程からの明示的な呼び出し指示でのみ起動する。 # Stopフックは直前のアシスタントターンが作業完了の言い切りで終わる場合だけ本スキルを誘導する。 # 本スキルは振り返りの唯一の外部入口であり、独立したsession-review-advisorが問題を列挙してメインが改善提案を確定する経路を必須とする。 --- # セッション振り返り本スキルは、セッション振り返りの手順を提供する唯一の外部入口である。独立した読み取り専用の`session-review-advisor`がtranscriptの問題と証拠位置を列挙し、メインが提案基準と環境固有観点を適用して改善提案を確定する。 ## 上位目的次のセッション以降でのユーザー介入と、レビュー指摘・手戻り・確認応答の反復コストを、妥当な恒久対策によって削減する。再発防止効果に見合わない恒常コンテキスト、工程、委譲、状態管理は追加しない。振り返り中にユーザーの割り込みや新規タスクが生じた場合は当該タスクを完遂し、中断前後の内容を点検対象に含めて振り返りを再開する。 ## 起動方針ユーザーからClaude Codeの`/agent-toolkit:session-review`またはCodexの `$agent-toolkit:session-review`で手動起動された場合は終了判定をせず、証拠収集へ進む。 Stop hookからの自動起動は、同一セッションで`process-feedbacks`、`plan-and-add-feedback`又は `add-feedback`のいずれかを実行した場合だけ行う。対象フラグが無い通常セッションはStop hookが振り返り誘導を表示せずに終了を許可する。手動起動は対象フラグの有無にかかわらず維持する。 Stopフックから呼ばれた場合は、直前のアシスタントターンが作業完了の言い切りで終わっている場合だけ進む。質問・確認・承認待ち、バックグラウンド処理待ち、外部完了通知待ちは完了に含めない。起動条件を満たさない場合は現在の状態と次の契機を示して終了する。起動済み状態の記録と後述の証拠再抽出では、ホスト別に現行plugin rootを確定する。 Claude Codeでは`${CLAUDE_PLUGIN_ROOT}`を現行plugin rootとして使う。 Codexでは、読み込んだ本`SKILL.md`の絶対パスの末尾成分が順に `skills`、`session-review`、`SKILL.md`と完全一致することを確認する。一致した固定末尾成分を一組として絶対パスから除き、残った接頭部分を現行plugin rootとする。固定末尾成分が一致しない場合又は対象スクリプトが実在する通常ファイルでない場合は、証拠収集へ進まず失敗を報告する。起動条件を満たして証拠収集へ進む場合、StopのreasonまたはUserPromptSubmitの`additionalContext`から `session_id`を受け取っていれば、起動済み状態を記録する。 Claude Codeでは次のコマンドを使う。 ```sh uv run --no-project --script ${CLAUDE_PLUGIN_ROOT}/scripts/session_review_state.py ``` Codexでは、次の``を確定済みの絶対パスへ置き換え、対象スクリプトが実在する通常ファイルであることを確認してから実行する。 ```sh uv run --no-project --script "/scripts/session_review_state.py" ``` 記録コマンドが失敗した場合は、証拠収集へ進まず失敗を報告する。 ## 証拠収集 Stopフック起動ではreason、ホスト別の手動コマンド起動では`additionalContext`から、同じpayload由来の `session_id`と`transcript_path`を受け取る。受け渡し専用の永続stateや証拠fileは作成しない。 `session-review-advisor`の起動前に`agent-toolkit:delegation`をSkill機能で起動する。起動時に必ず読み取り専用の`session-review-advisor`を1つ起動し、transcriptの絶対パスを渡す。 advisorはtranscript内で観測した問題と証拠位置だけを問題一覧として返す。問題の原因、対策及び改善提案の要否はメインが確定する。 - Stopフックのreasonまたは手動コマンドの`additionalContext`から受け取った`transcript_path`の絶対パス問題一覧と証拠位置の出力契約は`session-review-advisor`定義の出力を正本とし、起動文へ複製しない。 ## 観察対象観察対象を列挙する工程を開始する時は`agent-toolkit/skills/session-review/references/generation-criteria-detail.md`を全文読む。 Claude Codeの`~/.claude/references/session-review-dotfiles.md`又はCodexの`~/.codex/references/session-review-dotfiles.md`が存在する場合は、該当する文書もメインが全文読む。メインはadvisorの問題一覧を独立した観測入力として扱い、採否を確定済みの改善候補として扱わない。 ## 提案の確定メインはadvisorの問題一覧と再抽出証拠を`references/generation-criteria-detail.md`へ照合し、原因、対策及び採否を確定する。 ### ユーザー入力イベントの構造検収 advisor報告の`status`が`evidence_insufficient`の場合は、既存の証拠不足報告経路を維持し、証拠の再抽出、構造検収及び「提案無し」の確定へ進まない。 `status`が`completed`の場合だけ、受領済み`transcript_path`を既存の証拠抽出器へ一度だけ渡して、読み取り専用で既定の証拠を再抽出する。メインは既定の再抽出結果を`query=default`の照会結果としてそのまま使い、問題一覧が参照する`default`以外のdistinctな完全`query`文字列を、同じ引数列と順序で各1回だけ再実行する。異なる`--detail`引数列を1回の照会へまとめない。各`locator`が`event_index`だけを持ち、その値が0以上の整数であり、advisorが実行したものと同じ完全引数列の照会結果内に対象イベントが存在することを確認する。 locatorの形式が異なる、又は対象イベントが存在しない証拠を持つ問題は判断材料に用いない。 Claude Codeでは次のコマンドを使う。 ```sh uv run --no-project --script ${CLAUDE_PLUGIN_ROOT}/scripts/_session_review_evidence.py ``` Codexでは、起動方針で確定した現行plugin rootの絶対パスへ次の``を置き換える。 ```sh uv run --no-project --script "/scripts/_session_review_evidence.py" ``` 両ホストとも既存の抽出器とJSONL出力を再利用する。抽出器は手動起動と自動起動の全候補（Claudeの開始markerと Codexのstopに結び付く開始markerを含む）から、最新の適用可能な起動境界を共通に選ぶ。`finalize`・`stats`・`warning`は同じ選択結果を使い、境界後を保持するか除外するかは各利用経路の既存契約に従う。メインは再抽出結果の全`kind=user`イベントから`(sequence, line)`列を作成し、advisorの`checked_user_events`の値・件数・順序が一致することを機械的に確認する。 advisorが初回報告又は外部訂正後の返却で`evidence_insufficient`を返した場合、メインは既存の証拠不足報告経路へ進み、追加の訂正要求、利用者介入の分類、原因・処置の確定及び「提案無し」の確定へ進まない。初回照合で値・件数・順序が一致しない場合、メインは再抽出結果にだけ存在する不足`(sequence, line)`を再抽出順で、`checked_user_events`にだけ存在する余剰`(sequence, line)`を報告順で列挙する。メインは不足ID列と余剰ID列だけを同一advisor sessionへ返し、advisor定義の継続入力契約に従って初回報告を含む累積出力全体の訂正を1回だけ求める。利用者入力本文、問題分類又は対策は返さない。メインは訂正済み`completed`の累積出力へ、この節が定める問題一覧の証拠位置検収と`checked_user_events`の値・件数・順序の照合を再実行する。訂正後も値・件数・順序が一致しない場合は`evidence_insufficient`として既存の証拠不足報告経路へ進み、利用者介入の分類、原因・処置の確定及び「提案無し」の確定へ進まない。集合差だけでなく順序不一致も初回不一致として扱う。不足・余剰がともに空でも順序が異なる場合は、空の2列を同一advisor sessionへ返し、累積出力の訂正を1回だけ求める。訂正後の再検収で再び順序が異なれば`evidence_insufficient`へ終端する。メインはこの照合で問題か否かを再分類しない。メインはadvisorの問題一覧だけを対象に、利用者介入かその他の問題かを分類し、観測事象、原因、予防処置、介入前の発火契機を確定する。この構造検収のために新しい永続状態、所有者又は表示経路を追加しない。候補層の判定前に、メインは`atk mq list --status=active --target-repo= --skip-pull`を一度だけ実行し、`processing`配置を含む対象リポジトリの唯一のactive一覧を取得する。取得した各項目について、状態が`active`、対象リポジトリが同一、`process-loop`で処理可能であることを検証する。第1層から第3層までの全候補層の抑止判定は、この検収済み一覧を共通に用いる。証拠からエージェントの誤りがユーザー介入を招いたと確定した候補では、メインが`agent-toolkit:bugfix`を起動する。`agent-toolkit:bugfix`の深掘り契約に従い、直接的原因、混入要因、動機的要因、見逃し原因、根本原因、原因起点の類似見直し及び是正処置・横展開処置・再発防止処置を確定する。各根本原因を成立させる単位は、現行実装・テスト若しくは反復しない実測により有効性を確認した実装済み処置へ対応づける。検収済み一覧に含まれる、同一対象リポジトリで`process-loop`が処理できる有効なactiveフィードバックも対応先にできる。 activeフィードバックを被覆とする条件は、単なる処理可能性だけではない。フィードバック本文または対応計画が、対応づける各根本原因単位と、その単位に必要な是正処置・横展開処置・再発防止処置の全てを覆う根拠を確認する。既存規範への違反では、規範の存在を有効性の根拠にせず、規範が機能しなかった原因を処置へ含める。原因単位の被覆が部分的な場合は未被覆単位だけを候補とする。全単位が被覆される場合だけ「提案無し」を確定する。 activeフィードバックを被覆に使う場合は、ファイル名、状態、対象リポジトリ及び被覆単位を最終報告へ記録する。本文または対応計画が各根本原因単位と必要な処置の全てを覆う根拠、`process-loop`で処理できる根拠及び重複投入しない理由も記録する。実装済み処置を被覆に使う場合は、検証結果を記録する。反復しない実測を根拠にした場合も記録する。メインは問題一覧ごとに、自動ロード済みの規範を第一の照合対象として候補化、根本原因、反映先、既存手段、成功経路の喪失、総ライフサイクルコスト及び代替案を判断する。メインは既存規範・既存実装との重複を確認し、不足する場合だけ対象ファイルを追加で読む。併せて、反映先のファイルと節の実在、既存契約との整合、契約同期の成立性を確認する。採用する候補に限り、`generation-criteria-detail.md`「総ライフサイクルコスト」が定める契約同期検索として、対象パス・節名・識別子・入出力フィールド名・変更する規範文をリポジトリ全体で検索し、同時改訂を要するファイルとテストを列挙する。これらの照合・概念比較・契約同期検索はメインが所有し、advisorはtranscript内の問題と証拠位置の列挙だけを担う。 ## ユーザーコメントの由来 `source: session-review`の通常本文はエージェント由来とする。末尾のexact H2 `## ユーザーコメント`配下から導出した要求だけは人間由来とし、通常本文から導出した要求と分けて採否を記録する。両方にまたがる記述は独立して採否できる要求へ分解し、ファイル全体の由来を人間へ昇格させない。`source`の原値と予約節は要求の優先順位及び不採用時の確認境界を決める運用上の由来情報であり、push、公開、破壊的操作又は外部サービス変更のユーザー認可を証明しない。 session-review自身は予約見出しを提案本文に生成しない。UI外の一般全文編集が見出しを作成できる現行信頼境界は明記し、新しい認証、署名又は監査スキーマは追加しない。採用候補の反映先は、コードに近い仕組み、プロジェクト規範、配布規範、スキルの順に比較する。単発事象の言い換え、既存規範の重複、実在欠陥を解消しない好み、効果を裏付けられない工程追加は採用しない。既存規範への違反が観測された候補では、既存文面の再掲だけを重複として不採用にでき、違反の原因に対応する規範追加以外の階層の対策（機械検査、フック、工程・入力構造の変更）は重複として扱わない。既存規範への違反を根拠とする候補をメインが不採用とする場合は、規範追加以外の階層（機械検査、フック、工程・入力構造の変更）で検討した対策と不採用理由を最終報告へ記録する義務を負う。初回表示の前に、候補ごとに2件の反証を用意する。1件目は過剰設計の反証とし、「この候補は問題に対して過大である」と述べる最も強い反論とする。2件目は根本原因判定の反証とし、「同じ事象を別の根本原因で説明できる」又は「候補が事象の副次的な側面を根本原因と誤認している」と述べる最も強い反論とする。2件の反証のいずれか1件でも退けられない候補は採用しない。反証を退けられた場合も、過剰設計の反証が指摘した過大さを取り除いた最小十分な形へ縮小してから表示する。反証の作成に追加の`session-review-advisor`や追加調査工程は設けない。縮小の対象は反映先、分量、工程数とし、根本原因が示す是正手段の集合は減らさない（厳守規定。手段を除外すると根本原因の一部が対策されないまま提案が確定する）。同じ根本原因を持つ候補、または反映先と検証範囲が同じ候補は1件へ統合する。分割したまま表示できるのは、独立に採否を判定できる便益を示せる場合に限る。候補自身が記載した欠点が候補の期待する効果を失わせる場合は、2件の反証を経ずに採用しない。 ## 改善提案の表示表示本文の起草前に`agent-toolkit:writing-standards`をSkill機能で起動する。各欄は結論を先頭に置いて簡潔に書き、採否を左右する判断材料（代替案・費用・副作用・重複判定など）は削除せず後半の欄へ保持する。簡潔化は表現の圧縮で行い、判断材料の削除で行わない。採用する提案を次の形式でユーザーへ示す。プロジェクト固有の提案と、利用環境全体へ適用する提案を分ける。 dotfiles固有の参照文書を適用した候補は、利用環境全体の提案へ統合する。 ````text # 改善提案 ## プロジェクトドキュメント改善提案 ### [提案要約] - 反映内容: [自己完結した変更内容] - 反映先: [対象ファイルと節] - 理由: [観測事象と根本原因] - メリット: [期待効果] - デメリット: [総費用、副作用、運用負担] ## ユーザードキュメント改善提案 ### [提案要約] - 反映内容: [自己完結した変更内容] - 反映先: [対象ファイルと節] - 理由: [観測事象と根本原因] - メリット: [期待効果] - デメリット: [総費用、副作用、運用負担] ```` 提案がない章には「提案無し」と書く。実害がありエージェントの誤りが利用者介入を招いた問題で「提案無し」とする場合は、原因分析の結果と全根本原因単位の被覆根拠を併記する。実装済み処置を使う場合は検証結果を、activeフィードバックを使う場合はファイル名、状態及び対象リポジトリを併記する。activeフィードバックの本文又は対応計画が各根本原因単位と必要な処置の全てを覆う根拠、`process-loop`処理可能性、重複投入しない理由及び残余リスクも併記する。会話履歴を参照しなければ意味が定まらない表現を使わず、各提案を単独で実装判断できる粒度にする。理由には観測した具体事象を含める。 ## 改善提案の投入と終了表示した各提案は、実行主体が提案ごとに`agent-toolkit:add-feedback`をSkill機能で起動し、source `session-review`を明示して、本文を変えず完成済み入力として渡して投入する。対象リポジトリ、重複判定、保存結果の照合、警告時の修復は同スキルの契約に従う。振り返りが`agent-toolkit:process-feedbacks`の終了工程として起動された場合も、改善提案の投入完了後に実行主体が`agent-toolkit:exit-session`をSkill機能で起動する。通常の手動起動またはStopフック起動では、投入完了後に「セッション最終報告の共通枠」に従う最終報告を発行してターンを終える。表示後のユーザー発話は`agent-toolkit/rules/01-agent.md`「ユーザー発話の解釈」節に従って解釈する。提案的表現・疑問の対象となった候補は、反証と最小十分性の観点で評価し直してから採否を確定し、確定した処置を1回にまとめてキューへ反映する。ユーザーが提案を是正した場合は、登録本文だけでなく、誤った提案を通した前提または生成基準を特定し、一般化した再発防止を同じフィードバックまたは別フィードバックとして登録する。 ## セッション最終報告の共通枠本節は、session-reviewが通常の手動起動またはStopフック起動で完了する経路に適用する。 `agent-toolkit:process-feedbacks`の終了工程として起動された場合は`agent-toolkit:exit-session`が終端を担うため、本節を適用しない。セッションの最終報告は次の構成とする。 ```text <冒頭1文: 元タスクの完了可否の言い切り> ## 成果 - <元タスクのスキルが定める固定項目> ## 振り返り - 改善提案: `<ファイル名>`を投入（複数件は全ファイル名を列挙。無い場合は`提案無し`） ``` `## 成果`には、元タスクのスキルが完了報告で提示した固定項目を再掲する。元タスクのスキルが完了報告の固定項目を定めていない場合は、ユーザーが観測できる主要成果を同じ箇条書き形式で列挙する。 `## 振り返り`節はsession-review完了後の最終報告だけに置く。各スキルの完了報告は同節を含めないため、ユーザーは同節の有無でsession-review実施済みかを判別できる。最終報告のメッセージは前掲の構成だけとし、枠の前後へ前置き・補足・後書きの地の文を加えない。伝えるべき内容は冒頭1文、`## 成果`又は`## 振り返り`の項目へ収める。