anomaly-investigation

異常調査ループ

定式化 → 検証 → 除外 → 確認のループです。根本原因分析を探索として捉えます。成果物は調査ログで、フィードバックシグナルは有力な原因候補の数です。候補数を減らしていき、単に矛盾しないだけでなく、確認済みの単一の原因を目指します。各イテレーションでは、候補を1つデータに照らして検証し、データによって否定された候補を除外して、最後に1つだけ残るまで絞り込みます。

ここで徹底するのは、原因が「根本原因」と言えるのは、誠実に反証を試みても残り、かつ肯定的な予測が検証される場合だけだということです（例：「これが原因なら、取り除けば正常な状態に戻る」——実際に戻る）。異常を説明できる可能性があるだけの筋書きは、仮説であって、発見ではありません。

使用する場面

異常がすでに確認されており、何がおかしいのかをおおよそ把握していて、データに照らした消去法で原因を診断したい場合に使用します。まず、互いに区別できる広範な原因候補を並べ、次に候補を最も速く絞り込めるものを検証します。異常が曖昧な場合は、まずそれを明確にすることが作業になります（イテレーション 0）。追跡すべき異常がないデータセットを自由に探索する用途には使いません（data-analysis を使用してください）。また、文献に照らして外部の主張を検証する用途にも使いません（claim-verify を使用してください）。

セットアップ

バインディングは対話形式で解決します。作業ディレクトリに loop.run.yaml が存在する場合は読み込み、値を1行で確認してからループに進みます。それ以外の場合は、Claude Code（AskUserQuestion ツールが利用可能）では各バインディングの妥当な値を推測し、推奨オプションとして提示します。他のホストでは、それぞれを引用符付きのプレーンテキストの質問として尋ねます。その後、loop.run.yaml（形式：examples/run.example.yaml）を書き込み、ほかのファイルを作成する前に値を確認します。

binding	意味	デフォルト	推測方法
<dataset>	調査対象のデータ（またはログ）。読み取り専用の根拠データです	—	作業ディレクトリ内のデータファイル／ログファイルを検索します
<anomaly>	何がおかしいのか。指標、発生箇所／時期、偏差の大きさです	—	ユーザーに尋ね、イテレーション 0 で明確にします
<analysis_cmd>	ユーザーの環境で分析スニペットを実行するインタープリター	python3	作業ディレクトリ内の pyproject.toml／.venv／uv を確認します
<log>	調査ログの出力先	<sandbox_root>/investigation.md	—
<sandbox_root>	スニペットと台帳の保存場所	./sandbox	—
<budget>	イテレーションの最大数	8	—

分析スニペットは <analysis_cmd> を介してユーザーの環境で実行されるため、ユーザーがインストールしているものは何でも使用できます。ヘルパーコードは標準ライブラリを優先してください（csv、statistics）。スニペットで pandas／numpy が必要な場合は、try/except ImportError で確認して標準ライブラリを使う方法にフォールバックするか、同意を得たうえで uv pip install "pandas==<ver>" を提案してください。パッケージがインストール済みだと決めつけてはいけません。

ループ

このチェックリストをコピーして、項目にチェックを付けてください：

• イテレーション 0 — 異常を正確に特徴づけ、<log> に原因候補の初期リストを作成します。
• テストする候補を選びます（残る候補を最も明確に切り分けられるテストを行える候補を選びます）。
• テストします：<sandbox_root>/iter<N>/test.py を作成し、<analysis_cmd> で実行して、出力を out.txt にリダイレクトします。
• 排除（データが反証する → 現在の候補から外す）するか、継続（データが裏付ける → 候補として残す）します。
• 残った候補を確認します：候補が1つに絞られたら、反証を試みたうえで、その候補だけが予測する肯定的なテストを実行します。
• 台帳に1行追加します。原因が1つ確認されるか、<budget> に達したら終了します。

イテレーション 0 — 特徴づけ。 異常を正確に定量化します。何が、いつ／どこで、どの程度、通常のベースライン（前後の期間／セグメントにおける同じ指標）から逸脱したかを明確にするスニペットを作成し、実行します。その後、原因候補の初期リストを作成します。互いに区別でき、真の原因を含められる幅を持つ説明を挙げてください（実際の変化、構成／内訳の変化、データ品質のバグ、測定方法の変更、季節性、外れ値のセグメントなど）。候補として残すものを <log> に列挙します。まだ何も確認済みとして記録しないでください。

その後、終了条件（原因が1つ確認された場合、または予算に達した場合）を満たすまで、以下を繰り返します：

1. テストする候補を選びます。 各イテレーションでできるだけ多くの候補を除外できるよう、残る候補を最も明確に切り分けられるテストを行える候補を選ぶのが理想です。
2. テストします。 その候補を反証または裏付ける計算を行う <sandbox_root>/iter<N>/test.py を作成します（セグメント／ソース／時間で絞り込み、指標を再計算し、分布を比較します）。<analysis_cmd> で実行し、出力を <sandbox_root>/iter<N>/out.txt にリダイレクトします（コンテキストを出力で埋め尽くさないでください）。
3. 排除するか、継続します。
   • データが候補を反証する場合 → 根拠とともに <log> で排除済みと記録し、現在の候補から外します。
   • データが候補を裏付ける場合 → 候補として残します。さらに、その候補が最有力になった場合は、確認テストを実行します。確認テストでは、その候補だけが行う肯定的な予測を検証します（例：「疑わしい要因を取り除く／季節調整すると、異常が消える」）。また、候補を反証することも試みてください。真摯な反証の試みに耐え、確認テストにも合格した最有力候補が根本原因です。
4. 記録：台帳に1行追加し、候補を絞り込みながら続けます。

観測上の同等性。 仕組みの異なる2つの候補が、手元のデータに対して同一の予測をすることがあります（たとえば、ボットの大量アクセスとパイプラインの二重カウントは、日次集計ではどちらも「セッション数が急増し、コンバージョン数は横ばい」と見えることがあります）。その場合、ここでは区別できません。任意に一方を選ばないでください。手元のデータで可能な解像度では、これらを1つの確認済みの原因として報告し、区別するために追加で必要なデータ（より細粒度のログ、生イベント記録、上流の確認など）を示してください。また、指標がどう変化したかという仕組みと、入力データがなぜ誤っていたかという根本原因も区別してください。仕組みを確認できたことは前進ですが、それだけでは原因が特定されたことにはなりません。

台帳

<sandbox_root>/ledger.tsv はタブ区切りとし、テキストにカンマは使用しません。ヘッダー：

iter	candidate_tested	verdict	live_candidates

verdict は {characterize, refuted, supported, confirmed} のいずれかです。例：

iter	candidate_tested	verdict	live_candidates
0	characterize anomaly + slate	characterize	5
1	real drop across all segments	refuted	4
2	one segment's conversions fell	refuted	3
3	one source's sessions inflated	supported	2
4	removing that source restores normal	confirmed	1

確認された根本原因とその確認根拠、代替候補とそれぞれを除外した方法を報告してください。原因が1つも確認される前に終了する場合は、残る候補と、それらを区別するテストも報告してください。

制約

• 当てはめるだけでなく、確かめてください。 根本原因は、率直な反証を試みても残り、かつ肯定的な確認テストにも合格する必要があります。「データと矛盾しない」だけでは不十分です。通常、当てはまる説明はいくつもあるためです。
• 直感ではなく、データに照らしてテストしてください — 除外する候補も最終確認もすべて、実行して<log>に記録した計算で裏付けてください。
• 候補を見分けられる状態に保ち、候補群を最速で絞り込めるテストを優先して、有力候補の数を減らしてください。他の候補を未検証のままにして、特定の仮説だけを追いかけないでください。
• <dataset>のみを読み取ってください — 変更は決して加えないでください。すべてのテストで照合する正解データだからです。サンドボックスは自己完結しており、../による脱出はできません。
• 続行するかどうかを尋ねるためにループを中断しないでください。原因が確認されるか、予算に達するまで実行してください。

停止条件

• 確認済み — 反証を経て残った候補がちょうど1つで、肯定的な確認テストにも合格した状態です。
• 予算 — 確認済みの原因がないまま<budget>回の反復に達した場合です。有力候補の集合を報告してください。