session-debrief

自己進化型スキル：このスキルは使用するほど改善されます。指示が間違っている、パラメーターがずれている、または回避策が必要になった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現できる問題がある場合のみ更新してください。

実行モデル — 必須

エージェントを起動する前に、必ず AskUserQuestion を 2 回使用してください。 まず目標を尋ね、次に期間を尋ねます。その後、確定したパラメーターを使ってエージェントを起動してください。

---

ステップ 1 — 目標を尋ねる

AskUserQuestion を使って、次の 3 つの選択肢をそのまま提示してください。

どの分析モードを使用しますか？

1. 引き継ぎドキュメント — この作業を引き継ぐ次の開発者または Claude セッションのために、網羅的なコンテキストをまとめます。すべての決定事項、ファイル、コマンド、注意点、未完了項目、次の手順を抽出します。必要に応じて分割・統合し、全体を漏れなくカバーします。
2. エラーフォレンジック — 発生した警告、エラー、非推奨事項、失敗したコマンド、異常をすべて網羅します。特に Claude が認識しながら無視または先送りしたものを重視します。ファイルパスとコマンドを含め、詳細を一字一句そのまま記載します。
3. 時系列サマリー — 起きたことすべてを、決定、変更、問題、発見、結果の順にまとめた、密度の高い技術的なタイムラインです。できるだけ簡潔にしながら、最大限の出来事を記録します。

---

ステップ 2 — 期間を尋ねる

AskUserQuestion を使って、次のように尋ねてください。

どの期間までさかのぼってセッションを含めますか？

• 48 時間（デフォルト — 直近 2 日間）
• 1 週間（168 時間）
• 1 か月（720 時間）
• カスタム — 「3 日」「2 週間」「5 時間」「月曜日から」など、自然な言葉で入力してください

回答を --since <N> に指定する時間数に変換します。

• 「3 日」→ 72
• 「2 週間」→ 336
• 「5 時間」→ 5
• 「月曜日から」→ 現在から直近の月曜日までの時間数を計算

---

ステップ 3 — エージェントを起動する

Agent(
  description: "Session analysis - Goal <N>: <name>",
  prompt: "Run session analysis for the current project. Execute:

    bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \\
      --goal <1|2|3> \\
      --since <hours> \\
      --verbose

  Print all output exactly as-is. Do not filter or summarize.
  If the command fails, show the full error and suggest troubleshooting.",
  run_in_background: true
)

--shots は追加しないでください。これはレガシーの 50-perspectives モードにのみ適用されます。

エージェントから結果が返されたら、追加の要約をせず、そのままユーザーに提示してください。デブリーフ LLM の出力そのものが結果です。

---

セッションの見落とし — リファレンス

自己進化型スキル：このスキルは使用するほど改善されます。指示が間違っている、パラメーターがずれている、または回避策が必要になった場合は、先延ばしにせず、すぐにこのファイルを修正してください。実際に再現できる問題がある場合のみ更新してください。

3 つの目標

目標 1：引き継ぎドキュメント

最も包括的な出力モードです。質問をせずに作業を続けるために、次の開発者または AI セッションが必要とする情報をすべて抽出します。

出力構成：

• 達成したこと — 完了したすべてのタスク、ファイル、コマンド（網羅的に記載）
• 現在の状態 — 現時点で動作しているもの、変更されたもの
• 未完了／破損 — 未完了の項目、未解決のエラー、先送りされた作業
• 主な決定事項と理由 — なぜその方法で実施したのか
• 重要な注意点とコンテキスト — 一見わかりにくい事実、回避策、落とし穴
• 次の手順（優先順位順） — 次のセッションを開始するための具体的なアクション

抽出した履歴がスクリプトにハードコードされた上限（890K 文字、約 243K トークン。設定を参照）を超える場合、スクリプトはターンの区切りで分割し、各チャンクをデブリーフ LLM で分析した後、1 回の統合処理で部分分析をまとめます。部分分析が大きすぎて統合できない場合に限り、各パートを個別に出力します。3 つの目標はすべて同じ方法で分割されます。

目標 2：エラーフォレンジック

すべての警告、エラー、異常を記録します。特に Claude が対応を進めてしまったものを重視します。

各検出事項には、次の内容を含めます。

• 正確なターン番号
• 発生要因（原因となったコマンド／ツール）
• 関連するファイル／パス
• エラーの全文（言い換えず、そのまま記載）
• 解決状況：未解決／一部解決／解決済み
• Claude の対応（認識したか、無視したか、先送りしたか）

目標 3：時系列サマリー

密度の高い技術的なタイムラインとして、重要な出来事ごとに 1 つの箇条書きを作成し、発生順に並べます。

• 明確なフェーズがある場合は、フェーズごとにまとめます
• 未解決のエラーには ⚠ を付けます
• 決定事項とその理由を記録します
• 最後に主な成果（最も重要な結果を 3～7 件）を記載します

---

セッションの検出方法

このスクリプトは、時間枠内に更新された現在のプロジェクト（作業ディレクトリから特定）のすべてのセッションを自動的に見つけます。

1. ~/.claude/projects/<project-key>/ 内の .jsonl ファイルをスキャンします
2. --since の時間枠内に更新されたファイルを含めます
3. 各セッションについて、完全なコンテキストを得るため、親チェーン（継続セッション）をたどります
4. 一貫した流れになるよう、時系列順（古いものから）に並べ替えます

プロジェクトキーは、絶対パスの / を - に置き換えたものです。例：/Users/<you>/eon/cc-skills → -Users-<you>-eon-cc-skills

---

スクリプトの呼び出しリファレンス

# Focused goal mode — recommended
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 1 --since 48         # Handoff: last 48 hours
  --goal 2 --since 168        # Error forensics: last week
  --goal 3 --since 720        # Summary: last month

# Debug: show extracted payload without calling the LLM
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 1 --since 48 --dry --verbose

# Override project dir (if auto-detection fails)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 2 --since 48 --project-dir ~/.claude/projects/-Users-foo-myrepo

# Skip parent chain tracing (faster, current window only)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  --goal 3 --since 48 --no-chain

# Legacy 50-perspectives mode (single session UUID)
bun run $HOME/eon/cc-skills/plugins/devops-tools/scripts/session-debrief.ts \
  <session-uuid>

---

設定

設定	ソース	デフォルト
LLM API キー	DEBRIEF_LLM_API_KEY（または SUB2API_KEY）環境変数。それ以外の場合は、オペレーターの自己管理型保管庫：vault get cc-skills-tools-sub2api api_key	必須
LLM エンドポイント	DEBRIEF_LLM_API_URL 環境変数、または ${XDG_CONFIG_HOME:-~/.config}/cc-skills/debrief.env 内の DEBRIEF_LLM_API_URL= 行	必須、デフォルトなし
モデル	DEBRIEF_LLM_MODEL 環境変数（設定されているものはなく、実質的にハードコードされています）	claude-sonnet-5[1m]
最大出力トークン数	ハードコード	呼び出しあたり16384
コンテキスト予算	ハードコード	890K 文字（約243K トークン）
デフォルトの時間枠	--since	48時間
セッションの連結	無効にするには --no-chain	有効

---

最近のセッションを手動で見つける

# Sessions for current project (key = cwd with / replaced by -)
ls -lt ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl 2>/dev/null | head -10

# All projects, most recent first
ls -lt ~/.claude/projects/*/*.jsonl 2>/dev/null | head -20

---

トラブルシューティング

問題	原因	対処
Cannot determine project dir	CWD が既知のプロジェクトではありません	--project-dir ~/.claude/projects/<key> を使用します
No sessions found	指定した期間内にセッションがありません	--since の値を増やします（例：2週間の場合は --since 336）
could not resolve the debrief LLM key	環境にキーがなく、Vault の検索にも失敗しました	DEBRIEF_LLM_API_KEY をエクスポートするか、vault set cc-skills-tools-sub2api api_key で一度保存します
no LLM endpoint configured (exit 78)	DEBRIEF_LLM_API_URL が未設定です	エクスポートするか、~/.config/cc-skills/debrief.env に追加します
context window exceeds	1 つのセッションが大きすぎます	--dry --verbose でサイズを確認し、--no-chain を試します
出力が複数の PART セクションに分かれる	部分分析が大きすぎて統合できませんでした	想定される動作です。各パートは一連のターンの範囲を扱います

実行後の振り返り

このスキルの実行が完了したら、タスクを終了する前に振り返ってください。

0. 自分の位置を確認する。 — 編集する前に、この SKILL.md の正規パスを確認します。
1. 何が失敗したか？ — 原因となった指示を修正します。
2. 予想以上にうまくいったことは？ — 推奨プラクティスに追加します。
3. 何が現状とずれていたか？ — 実情に合わなくなったスクリプト、参照、依存関係を修正します。
4. 記録する。 — トリガー、修正内容、根拠を含む進化ログの項目を作成します。

先送りしてはいけません。次回の実行では、あなたが残した状態が引き継がれます。