trace

トレーススキル

クイックリファレンス： CASS セッション、引き継ぎ、git、成果物を通じて設計上の決定を追跡します。出力先：.agents/research/YYYY-MM-DD-trace-*.md

このワークフローは必ず実行してください。説明するだけではいけません。

使用する場面

• アーキテクチャ上の決定がどのように進化したかを追跡する
• 概念がいつ導入されたかを見つける
• ある設計がなぜ採用されたのかを理解する
• 設計上の決定の来歴をたどる

ナレッジ成果物の系譜（学び、パターン、ティア）については、代わりに $curate --mode=provenance を使用してください。

CLI の依存関係： cass（セッション検索）。cass を利用できない場合は、トランスクリプト検索をスキップし、git log、引き継ぎドキュメント、.agents/ の成果物を頼りに決定の経緯を追跡してください。

実行手順

/trace <concept> が指定された場合：

ステップ 1：対象の種類を分類する

追跡する来歴の種類を判断します。

IF target is a file path (contains "/" or "."):
  → Use `$curate --mode=provenance` (artifact lineage)

IF target is a git ref (sha, branch, tag):
  → Use git-based tracing (Step 2b)

ELSE (keyword/concept):
  → Use design decision tracing (Step 2a)

ステップ 2a：設計上の決定を追跡する（概念）

4 つの検索エージェント（CASS、Handoff、Git、Research）を並行して起動し、すべての処理が完了するまで待ちます。

バックエンド： エージェントは Task(subagent_type="Explore") を使用します。これは OpenCode では task(subagent_type="explore") に対応します。共有仕様については、skills/shared/SKILL.md の「Runtime-Native Spawn Backend Selection」を参照してください。

エージェントの定義とプロンプトについては、references/discovery-patterns.md を読んでください。

ステップ 2b：Git に基づいて追跡する（コミット／参照）

Git に基づく追跡コマンドについては、references/discovery-patterns.md を読んでください。

ステップ 3：タイムラインを作成する

すべての情報源から得た結果を、1 つの時系列タイムライン（古い順）にまとめます。同じ日／同じセッションのイベントは重複を除きます。すべての主張に出典を明記してください。

ステップ 4：重要な決定を抽出する

タイムラインの各イベントについて、以下を特定します。

• 変更点： 決定または変化
• 理由： 分かる場合は、その理由
• 担当者： セッション／著者／コミット作成者
• 証拠： 出典へのリンク（セッションパス、ファイル、コミット）

ステップ 5：トレースレポートを作成する

書き込み先： .agents/research/YYYY-MM-DD-trace-<concept-slug>.md

レポートの形式と重複排除のルールについては、references/report-template.md を読んでください。

ステップ 6：ユーザーに報告する

以下をユーザーに伝えます。

1. 概念の追跡が完了したこと
2. 進化のタイムライン（重要な日付）
3. 最も重要な決定
4. トレースレポートの場所
5. さらに調査できる関連概念

エッジケースへの対応

CASS の検索結果がない場合、引き継ぎがない場合、概念が曖昧な場合（検索結果が 20 件を超える場合）、およびすべての情報源が空の場合の対応については、references/edge-cases.md を読んでください。基本方針として、残りの情報源を使って処理を続け、レポートに不足情報を記載してください。

重要なルール

• すべての情報源を検索する — CASS、引き継ぎ、git、調査資料
• タイムラインを作成する — 時系列での変化を追うことが目的です
• 証拠を引用する — すべての主張に出典が必要です
• 不足情報には柔軟に対応する — すべての概念がすべての情報源にあるとは限りません
• レポートを作成する — トレースでは .agents/research/ に成果物を作成する必要があります

成果物の来歴との関係

スキル	目的	入力	出力
$curate --mode=provenance	成果物の系譜	ファイルパス	ティア／昇格の履歴
/trace	設計上の決定	概念／キーワード	変化のタイムライン

「この学びはどこから来たのか？」には $curate --mode=provenance を使用してください。 「このアーキテクチャはどのように決定されたのか？」には /trace を使用してください。

例

# Trace a design decision
/trace "three-level architecture"

# Trace a role/concept
/trace "Chiron"

# Trace a pattern
/trace "brownian ratchet"

# Trace a feature
/trace "parallel wave execution"

アーキテクチャ上の決定を追跡する

ユーザーの入力： /trace "agent team protocol"

処理内容：

1. エージェントが対象を概念として分類します（ファイルパスや git ref ではありません）。
2. エージェントが 4 つの並列エージェントを起動します：CASS 検索、ハンドオフ検索、git log 検索、調査成果物検索。
3. CASS が「agent team」に言及するセッションを 8 件、ハンドオフ検索がドキュメントを 2 件、git 検索がコミットを 3 件、調査検索が分析を 1 件見つけます。
4. エージェントが、最初の言及があった 2026-01-15 から最新の更新があった 2026-02-08 までの時系列を作成します。
5. エージェントが 5 つの重要な決定を抽出します：初期の SendMessage 設計、TeamCreate の追加、熟議プロトコル、インプロセスモード、委任モード。
6. エージェントが、完全な時系列と引用を含む追跡レポートを .agents/research/2026-02-13-trace-agent-team-protocol.md に書き込みます。

結果： 引用元を示しながら、7 つのセッションにわたるエージェントチームプロトコルの変遷を示す完全な時系列が作成されます。

Git コミットから追跡する

ユーザーの入力： /trace abc1234

処理内容：

1. エージェントが git ref 形式（短縮 SHA）を検出します。
2. エージェントが git ベースの追跡コマンドを実行し、コミットの詳細、変更されたファイル、関連コミットを取得します。
3. エージェントが git log --grep を使って関連する作業を検索します。
4. エージェントが .agents/ 内で同時期の調査や計画を検索します。
5. エージェントが、その変更に焦点を当てた時系列を作成します。
6. エージェントが、コミットの背景、変更内容、変更理由（コミットメッセージと関連ドキュメントに基づく）を示すレポートを書き込みます。

結果： 追跡レポートで、コミットを周辺の成果物から把握できる、より広範な設計背景に関連付けます。

トラブルシューティング

問題	原因	解決策
CASS で結果が返されない	セッション検索がインストールされていないか、クエリが具体的すぎます	which cass を確認します。見つからない場合は CASS を省略し、ハンドオフ、git、調査に頼ります。より広範な検索語を試します。
時系列に抜けがある	検索可能な成果物に、すべての決定が記録されているわけではありません	レポートに抜けがあることを記載します。チームメンバーへの聞き取りや、Slack／メールのアーカイブの確認を提案し、不足している背景を補います。
結果が多すぎる（50 件超）	概念が非常に広いか、頻出する用語です	あいまいな概念の扱いについては、references/edge-cases.md を参照します。クエリを絞るか、日付範囲でフィルタリングします。追跡する対象をより具体的にするようユーザーに尋ねます。
追跡レポートが空（すべてのソースで失敗）	概念が実際に文書化されていないか、誤字があります	スペルを確認します。同義語を試します。ユーザーに「文書化された履歴は見つかりませんでした。これは新しい概念か、別の検索語が必要な可能性があります」と報告します。

参考ドキュメント

• references/trace.feature — 実行可能な仕様：対象タイプの振り分け、複数ソースの並列検索、引用付き時系列、重要な決定の抽出、レポートと不足情報の適切な処理（soc-qk4b）
• references/discovery-patterns.md — 検索エージェントの定義と git ベースの追跡コマンド
• references/report-template.md — 追跡レポートの形式と重複排除ルール
• references/edge-cases.md — 空またはあいまいなソースの処理