trace

Trace スキル

観察された結果を直接修正したり、コードを書き換えたりするのではなく、なぜその結果が起きたのかを説明することが目的となる、曖昧で、因果関係があり、証拠を多く必要とする質問には、このスキルを使います。

これは、組み込みの tracer エージェント上にあるオーケストレーション層です。トレースを再利用可能な OMC の作業レーンとして機能させることを目的としています。観察内容を言い直し、競合する説明を生成し、並行して証拠を集め、説明を順位付けし、不確実性を最も速く解消できる次の調査を提案します。

適切な利用ケース

問題が次のような場合は、/oh-my-claudecode:trace を使います。

• 曖昧である
• 因果関係を扱う
• 多くの証拠を必要とする
• 競合する説明を並行して調べることで最善の回答が得られる

例：

• ランタイムのバグやリグレッション
• パフォーマンス／レイテンシ／リソースの挙動
• アーキテクチャ／プレモーテム／ポストモーテム分析
• 科学的または実験的な結果のトレース
• 設定／ルーティング／オーケストレーションの挙動の説明
• 「この出力から、考えられる原因をさかのぼって調べてください」

トレースの基本契約

次の区別を必ず維持します。

1. 観察内容 -- 実際に観察されたこと
2. 仮説 -- 競合する説明
3. 裏付ける証拠 -- 各説明を支持するもの
4. 反証する証拠／不足事項 -- 説明と矛盾するもの、または不足しているもの
5. 現時点で最善の説明 -- 現時点で最有力の説明
6. 重要な不明点 -- 上位の説明を分けている未確認の事実
7. 識別力のある調査 -- 不確実性を解消するために次に行うべき最も価値の高いステップ

次のようなものにまとめてしまわないでください。

• 汎用的な修正・実装の反復
• 汎用的なデバッガーの要約
• ワーカー出力の生データ
• 証拠が不十分なのに確実であるかのように装うこと

証拠の強さの階層

証拠を同列ではなく、順位付けされたものとして扱います。

強いものから弱いものの順：

1. 制御された再現／直接的な実験／説明を一意に識別できる成果物
2. 出所が明確な一次資料（トレースイベント、ログ、メトリクス、ベンチマーク出力、設定、git 履歴、ファイルと行番号に基づく挙動）
3. 複数の独立した情報源が同じ説明に収束しているもの
4. 単一の情報源に基づくコードパスまたは挙動の推論
5. 弱い状況証拠（タイミング、命名、スタック順、過去のバグとの類似性）
6. 直感／類推／推測

より強い階層の証拠が矛盾している場合、主に下位の階層に依存する仮説の順位を明示的に下げます。

強い反証／否定のルール

すべての本格的な /trace 実行で、最有力の説明を反証しようとする必要があります。

上位の各仮説について、次を行います。

• 仮説を裏付ける証拠を集める
• 仮説に反する証拠を集める
• 仮説が導く特徴的な予測を述べる
• 仮説と整合させにくい観察内容を述べる
• 次点の代替案との違いを見分ける、最も低コストな調査を特定する

次の場合、仮説の順位を下げます。

• 直接的な証拠と矛盾している
• 未検証の新たな前提を追加しないと成立しない
• 競合する仮説と比べて、特徴的な予測をしない
• より強い代替案が、より少ない前提で同じ事実を説明できる
• 裏付けの大半が状況証拠である一方、競合する仮説のほうが強い証拠階層に支えられている

チームモードのオーケストレーションの形式

/trace では Claude 組み込みチームモードを使います。

リードは次を行います。

1. 観察された結果または「なぜ」という質問を正確に言い直す
2. トレース対象を抽出する
3. 意図的に異なる複数の候補仮説を生成する
4. チームモードで、デフォルトで 3 つの tracer レーンを起動する
5. 各レーンに 1 人の tracer ワーカーを割り当てる
6. 各 tracer ワーカーに、担当レーンを裏付ける証拠と反する証拠の両方を集めるよう指示する
7. 最有力の仮説と、最も有力な残りの代替案との間で反論ラウンドを行う
8. 上位のレーンが実際に異なるのか、それとも同じ根本原因に収束しているのかを見極める
9. 重要な不明点と識別力のある調査を明示した、順位付きの統合結果にまとめる

重要：ワーカーには、同じ説明を並行して追わせるのではなく、意図的に異なる説明を追わせます。

v1 のデフォルト仮説レーン

プロンプトから、より適切な分類が強く示唆されない限り、次の3つのデフォルトレーンを使用してください。

1. コードパス／実装上の原因
2. 設定／環境／オーケストレーション上の原因
3. 測定／アーティファクト／前提の不一致による原因 — システム上の欠陥だけでなく、検証方法の欠陥も対象とします。例：検証クエリで、異なるエンティティ、テナント、ストリーム、グループ間で同じディメンションキーを使い回している、比較フィルターの形式がスキーマの粒度と一致していない、列挙による確認なしにカタログ名や列名がランタイム間で共通だと想定されていた、などです。複数エンティティにまたがる前提／キーの不一致も含みます。

レーン3では、エスカレーションする前に、エンティティをまたぐ不一致について前提を監査する必要があります。エンティティのディメンションを列挙し、ゼロ行または不一致という結果が、システム上の欠陥ではなく、複数のエンティティに1つのキーを適用したことによるものかを確認してください。これは検証方法の欠陥である可能性があります。

これらのデフォルトは、バグ、パフォーマンス、アーキテクチャ、実験のトレース全体で最初の分析が機能するよう、意図的に幅広く設定されています。

必須のクロスチェック観点

最初のエビデンス確認の後、該当する場合は次の観点から有力な仮説を検証してください。

• システム観点 — キュー、再試行、バックプレッシャー、フィードバックループ、上流／下流の依存関係、境界での障害、調整による影響
• プレモーテム観点 — 現時点で最有力の説明が不完全、または誤りだと仮定します。後からトレースを見返したとき、どの障害モードが見落とされていると問題になるでしょうか？
• 科学的観点 — 対照、交絡因子、測定バイアス、代替変数、反証可能な予測

これらの観点を、単なる形式的な確認にしてはいけません。見落とされた説明、隠れた依存関係、弱い推論を明らかにできる場合に活用してください。

ワーカーの責務

各ワーカーは、汎用的な実行役ではなく、tracer レーンの担当者として動作する必要があります。

各ワーカーは次のことを行う必要があります。

• 1つの仮説レーンだけを担当する
• 担当レーンの仮説を明示的に言い換える
• そのレーンを支持するエビデンスを収集する
• そのレーンに反するエビデンスを収集する
• 自説を支えるエビデンスの強さを順位付けする
• 不足しているエビデンス、予測との不一致、残る不確実性を指摘する
• そのレーンにおける重大な未知事項を明示する
• レーンに特化した最適な識別プローブを提案する
• 明示的な指示がない限り、実装に踏み込まない

有用なエビデンスの情報源には、次のものがあります。

• 関連するコード、テスト、設定、ドキュメント、ログ、出力、ベンチマークアーティファクト
• trace_timeline を使った既存のトレースアーティファクト
• trace_summary を使った既存の集約トレースエビデンス

ワーカーの回答には、次の構成を推奨します。

1. レーン
2. 仮説
3. 支持するエビデンス
4. 反するエビデンス／不足事項
5. エビデンスの強さ
6. 重大な未知事項
7. 最適な識別プローブ
8. 確信度

リーダーによる統合の責務

最終的な /trace の回答は、単に各結果を並べるのではなく、統合する必要があります。

次の項目を含めてください。

1. 観測された結果
2. 順位付けされた仮説
3. 仮説ごとのエビデンスの要約
4. 反するエビデンス／不足しているエビデンス
5. 反論ラウンド
6. 収束／相違に関する注記
7. 最も可能性の高い説明
8. 重大な未知事項
9. 推奨する識別プローブ
10. 追加のトレースレーン（任意。不確実性が依然として高い場合のみ）

現時点で1つの説明が優勢であっても、順位付けされた候補リストを残してください。

反論ラウンドと収束の検出

トレースを終える前に、次のことを行ってください。

• 最有力ではないレーンのうち、最も強いレーンに、現時点での最有力仮説への最善の反論を提示させる
• 最有力の仮説を支持する側に、主張ではなくエビデンスを使って反論に答えさせる
• 反論によって最有力仮説が大きく弱まる場合は、順位表を更新する
• 「異なる」2つの仮説が同じ根本的なメカニズムに帰着する場合は、統合し、その旨を明示する
• 2つの仮説が次に行うプローブについて異なる示唆を持つ場合は、似て聞こえても別々に保つ

複数のワーカーが似た表現を使っているというだけで、収束したと主張してはいけません。収束とみなすには、次のいずれかが必要です。

• 同じ根本的な因果メカニズムであること
• 独立したエビデンスの流れが、同じ説明を示していること

明示的な順位引き下げの指針

筆頭の説明では、ある仮説の順位を下げた理由を明示してください。

• より強い証拠と矛盾している
• 予測していた観察結果が得られていない
• その場しのぎの追加仮定が必要になる
• 筆頭の仮説より説明できる事実が少ない
• 反論ラウンドで劣勢になった
• より強力な親説明に収束した

これは重要です。/trace では、最終的な表を示すだけでなく、ある説明が別の説明より上位になる理由を読者に伝える必要があります。

推奨する筆頭プロンプトの骨子

次のような、チーム指向のオーケストレーションプロンプトを使用してください。

1. 「観察結果を正確に言い直してください。」
2. 「意図的に異なる3つの仮説を生成してください。」
3. 「Claude の組み込みチームモードを使い、仮説ごとにトレーサーレーンを1つ作成してください。」
4. 「各レーンについて、賛成・反対の証拠を集め、証拠の強さを順位付けし、重要な未知事項と最適な識別プローブを挙げてください。」
5. 「有用であれば、筆頭の仮説にシステム、プレモーテム、科学の各視点を適用してください。」
6. 「上位2つの説明の間で反論ラウンドを実施してください。」
7. 「順位付けした説明の表、収束に関するメモ、重要な未知事項、単一の最適な識別プローブを返してください。」

出力品質の基準

優れた /trace の出力は、次の条件を満たします。

• 証拠に裏付けられている
• 簡潔でありながら厳密である
• 拙速な確信に懐疑的である
• 不足している証拠を明示している
• 次の行動が実践的である
• 弱い説明の順位を下げた理由が明確である

最終的な統合結果の形式例

観察された結果

[何が起きたか]

仮説の順位

順位	仮説	確信度	証拠の強さ	筆頭である理由
1	...	高／中／低	強／中程度／弱	...

仮説ごとの証拠の概要

• 仮説 1：...
• 仮説 2：...
• 仮説 3：...

反証となる証拠／不足している証拠

• 仮説 1：...
• 仮説 2：...
• 仮説 3：...

反論ラウンド

• 筆頭の仮説に対する最も有力な反論：...
• 筆頭の仮説が維持された／退けられた理由：...

収束／分離に関するメモ

• ...

最も可能性の高い説明

[現時点で最適な説明]

重要な未知事項

[不確実性が残る原因となっている、唯一の未確認事実]

推奨する識別プローブ

[次に行う単一のプローブ]

追加のトレースレーン

[不確実性が依然として高い場合のみ]