data-analysis

データ分析ループ

データセットを対象にした仮説 → 検証の振り返りループです。成果物は分析結果レポートで、フィードバックのシグナルは検証です。計算を再実行し、意味のある効果量が確認された場合にのみ、分析結果として認められます。このループで徹底することは、**数値の裏付けがない洞察は出さないことです。**データが裏付けないもっともらしい主張は、表現を弱めるのではなく破棄します。レポートのすべての記述はデータセットから再現できます。

使用するタイミング

それぞれの分析結果を独立した再計算に耐えさせる必要がある、バインド済みデータセットの自由度が高く自己検証を行う探索に使用します。デフォルトでは各列を幅広く探索します。ユーザーが注目する質問を提示した場合は、それを仮説の指針にします。既知の異常を1つ診断する場合や、外部の主張を文献と照らし合わせて確認する場合には使用しません。

セットアップ

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

binding	意味	デフォルト	推定方法
<dataset>	分析するデータファイル（CSV/TSV/Parquet/…）。読み取り専用のグラウンドトゥルース	—	作業ディレクトリ内のデータファイルをスキャンする
<question>	任意の分析の焦点。広く探索する場合は省略	—	ユーザーに尋ねる。それ以外は未バインドのままにする
<report>	分析結果の出力ファイル	<sandbox_root>/findings.md	—
<analysis_cmd>	ユーザーの環境で分析スニペットを実行するインタープリター	python3	作業ディレクトリ内のpyproject.toml/.venv/uv
<sandbox_root>	スニペットと台帳を置く場所	./sandbox	—
<budget>	最大反復回数	8	—
<patience>	新たに検証された分析結果がない状態で連続して N 回反復したら停止する	2	—

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

ループ

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

• イテレーション 0 — <dataset> のプロファイルを作成します（形状、型、範囲、欠損状況）。所見としては何も記録しません。
• 具体的で検証可能な仮説を 1 つ提案します（<question> に沿ったもので、すでに結論が出ていないもの）。
• 算出します：<sandbox_root>/iter<N>/analysis.py を作成し、<analysis_cmd> で実行して、出力を out.txt にリダイレクトします。
• 検証します：主要な数値を別の方法でもう一度導き出し、明示した効果量の基準に照らして評価します。
• 仮説を支持する場合 → <report> に所見を追加します（verified）。それ以外の場合は refuted と記録し、追加しません。
• 台帳に 1 行追加します。停滞（<patience>）または <budget> に達したら停止します。

イテレーション 0 — プロファイル作成。 <dataset> の形状を報告するスニペットを作成して実行します。列、推定された型、行数、簡単な要約（範囲、カテゴリごとの件数、欠損状況）を報告します。これを仮説の基礎とし、この時点では所見を何も記録しません。

停止条件に達するまで（新たな結果が得られなくなるか、予算に達するまで）：

1. 仮説を 1 つ提案します。 具体的で検証可能な主張を 1 つ提示します。例：「エンタープライズの注文はコンシューマーより平均値が高い」「モバイルは他のチャネルより返品率が高い」「登録からの期間が長いほど注文金額が上がる」などです。<question> に沿ったものとし、すでに結論が出た仮説を繰り返さないでください。
2. 算出します。 <dataset> を読み込み、関連する統計量 と効果量（グループ平均の差、率の差、相関など。はい／いいえだけではありません）を算出する <sandbox_root>/iter<N>/analysis.py を作成します。<analysis_cmd> で実行し、出力を <sandbox_root>/iter<N>/out.txt にリダイレクトします（コンテキストを出力であふれさせないでください）。
3. 検証 — 判定の関門です。 主要な数値を、独立した別の方法（異なるグループ分け、再集計、妥当性の簡易確認など）でもう一度導き出し、2 つの値が一致することを確認します。次に、結果を率直に評価します。結果は 意味のある効果量で仮説を支持していますか、それとも無視できる程度／ノイズの範囲内ですか？「意味がある」かどうかは、事前に設定した基準に照らして一貫して判定します。グループのサイズとノイズに応じた最小効果量を基準にしてください（例：おおよそ |Cohen's d| ≳ 0.2、リスク比 ≳ 1.5、または |r| ≳ 0.1。グループが小さい場合は、基準を厳しくします）。これにより、採用／棄却の基準がイテレーションごとに変わるのを防ぎます。
   • 支持された場合 → <report> に所見を追加します。主張、正確な数値、効果量、再現可能な手法を記載してください。verified とマークします。
   • 支持されない／効果が無視できる場合 → 台帳に refuted と記録し、レポートには追加しません。帰無結果も正当な結果であり、隠すべき失敗ではありません。
4. 記録 — 台帳に 1 行追加して続行します。

台帳

<sandbox_root>/ledger.tsv はタブ区切りとし、テキスト内でカンマを使用しないでください。ヘッダー：

iter	hypothesis	effect	status

status は profile、verified、refuted のいずれかです。例：

iter	hypothesis	effect	status
0	dataset profile	-	profile
1	enterprise orders average higher value than consumer	185 vs 109 (+70%)	verified
2	returns differ by region	North 0.16 vs South 0.14 (negligible)	refuted
3	mobile has a higher return rate than web/store	0.30 vs 0.10	verified

最も良い結果を報告してください。<report> のパス、検証済みの所見の件数、および棄却した仮説を示します（ユーザーが、残った結果だけでなく、何を確認して除外したのかも把握できるようにします）。

制約

• 数値を算出していない主張は禁止です。 <report> の各所見には数値と、その算出方法を記載してください。算出できない場合は、主張できません。
• 記録する前に検証します。 ステップ 3 の独立した再算出が判定の関門です。再現されない所見や、効果がノイズの範囲内にある所見は、レポートに含めません。
• 方向だけでなく効果量を報告し、相関を因果関係として誇張しないでください。「関連している」と表現し、データから交絡因子を切り分けられない場合はその旨を記載します。
• イテレーションごとに仮説は 1 つだけとし、各所見の根拠を明確にします。すでに結論が出ている仮説は飛ばします。
• <dataset> だけを読み取ります。変更してはいけません。すべての所見の検証対象となる正解データだからです。サンドボックスは自己完結しており、../ による脱出は禁止です。
• 続行するかを尋ねるためにループを中断しないでください。新たな結果が得られなくなるか、予算に達するまで実行します。

停止条件

• 新たな結果なし — <patience> 回連続で、検証済みの新しい所見が追加されない場合。
• 予算 — <budget> 回のイテレーションに達した場合。