compare

比較：トラッカー間で同じエポックの実行を比較する

最もよくある比較ミスは、実行 A が 100 エポック中 11 エポック目の時点で、ベースラインの値が 100 エポック目のものであるにもかかわらず、「実行 A はベースラインより 4 パーセントポイント遅れている」と報告することです。学生側は まだ学習中 なので、この比較には意味がありません。このスキルでは、同じエポックで比較することを徹底します。

エージェント型の Stop フックは、アシスタントが実行間の差を同じ段階にそろえずに報告すると、reason からここに誘導します。

「X はなぜ失敗した／発散した／性能が劣ったのか」という質問の場合は、まず /labrat:debug に進んでください。

トラッカーを自動検出する

次の順序で確認します。

1. WANDB_API_KEY 環境変数が設定されている、wandb がインポートされている、またはプロジェクト内に wandb のキーを含む *.yaml 設定ファイルがある → wandb
2. NEPTUNE_API_TOKEN 環境変数が設定されている、または neptune のキーを含む *.yaml 設定ファイルがある → neptune
3. MLFLOW_TRACKING_URI 環境変数が設定されている、または mlruns/ ディレクトリがある → mlflow
4. runs/ または lightning_logs/ ディレクトリがある → tensorboard
5. 実行ディレクトリに *results*.json / *meta*.json / eval*.csv ファイルがある → ローカルファイル形式：サンプルファイルを 1 つ読み、その形式に対応した分析コードを記述します。固定のスクリプトは使いません。

どれにも該当しない場合は、推測する前にメトリクスの保存場所をユーザーに尋ねます。

手順

1. 実行を特定する

省略名ではなく、完全な名前を確認します。ユーザーが「run-b とベースライン」と言った場合は、次の点を確認します。

• どの run-b の実行か（プロジェクト + エンティティ + run-id）
• どのベースラインか（完全な実行名。ベースラインには複数のバリエーションがあることがよくあります）

2. メトリクスの履歴を取得する（最終値だけではなく）

最後に報告された値ではなく、曲線全体が必要です。最終値だけの比較では、収束の動態が見えなくなります。

wandb の場合：

import wandb
api = wandb.Api()
run = api.run("entity/project/run-id")
history = run.history(samples=10000)  # full history, not just summary

tensorboard の場合は、イベントファイルを解析します（tensorboard.backend.event_processing.event_accumulator.EventAccumulator）。

neptune / mlflow の場合は、それぞれの API を使います。

3. 学生側の現在のステップを確認する

学生側とは、進行中の実行（または評価対象の実行）です。最新の履歴行から、現在のエポック／ステップを取得します。

4. ベースラインを同じステップで切り出す

ここが重要なステップです。ベースラインは（たとえば）エポック 100 まで進んでいても、学生側はエポック 11 の時点です。ベースラインのメトリクスはエポック 100 ではなく、エポック 11 の値を取得します。

student_step = student_history['epoch'].max()
baseline_at_same_step = baseline_history[baseline_history['epoch'] == student_step]

ベースラインに完全に一致するステップがない場合は、補間するか最も近いステップを選びます。どちらを使ったか明記します。

5. プロキシメトリクスと下流メトリクスを分ける

多くの ML パイプラインには、プロキシメトリクス（計算コストが低く、学習中に計算されるもの。特徴量に対する kNN 精度、損失、パープレキシティなど）と、目標となる下流メトリクス（計算コストが高く、定期的に、または学習の最後にのみ計算されるもの。ファインチューニング済み線形プローブの精度、下流タスクの F1 など）があります。

プロキシメトリクスは収束の追跡に使い、目標となる下流メトリクスはプロジェクトが実際に最適化している指標です。プロキシメトリクスだけを報告すると誤解を招くことがあります。kNN で遅れている実行も、下流のファインチューニングでは差を縮める可能性があります。両方を分けて報告します。

                        | student (ep 11) | baseline (ep 11) | delta |
| proxy (kNN top-1)     | 36.4%           | 38.9%            | -2.5  |
| downstream (linear)   | not yet         | 42.1%            | n/a   |

ユーザーがプロキシデータしか持っていない場合は、そのことを明示します。プロキシだけを根拠に勝者を決めてはいけません。

6. 出力における実行名

レポートのすべての行で、完全な実行名を使います。run-a vs run-b ではなく、必ず imagenet-resnet50-baseline-bs256 vs imagenet-resnet50-distill-from-vit-l のように記載します。後でこれを読む自分は、省略名を覚えていないからです。

避けるべきパターン

• 「X はベースラインより 4pp 遅れている」：どのステップの時点か を明記していません。ほとんどの場合、誤りです。
• 「X は収束した」：曲線の直近 5 エポックを示していません。
• 「最良の実行は Y」：実行ごとに異なる方法で記録されたメトリクス（異なる集約方法、異なる評価セットなど）に基づいています。
• シードが 1 つだけの比較を決定的なものとして扱う。分散がわかっている場合は記載し、わからない場合はシードが 1 つだけの比較であると明記します。

出力

メトリクスのペア（プロキシ + 下流）ごとに、簡潔な比較表を作成します。各行は学生側の現在のステップにそろえます。各セルの値は、特定のトラッカーの run-id とステップまでたどれるようにします。最後に、比較を解釈する文を 1～2 文添えます。「現在の傾きから推定すると、ステップ N で学生側が追いつく見込みです」は有用な表現です。一方、収束前に「学生側が勝っている／負けている」と断定するのは、ほとんどの場合妥当ではありません。

2 つを超える実行：ランキング、レポート、アブレーション、モニタリング

複数の実行をランキングする

主要な指標以外も含めて実行を比較します。

• 主要な指標（精度、F1、損失）
• 学習の動態（収束速度、安定性）
• リソース使用量（GPU 時間、メモリ、コスト）
• ハイパーパラメーターの違い

以下の実験レポートの結果テーブルにまとめ、次を特定します。

• 全体で最良の実行
• 指標ごとに最良の実行
• 最も効率的な実行（GPU 時間あたりの指標が最良）
• クラッシュした実行、または異常があった実行

アブレーション分析

1. ベースラインの実行を特定します
2. 各アブレーションについて、ベースラインからの差分を計算します
3. 影響の大きさで順位付けします
4. 相互作用の影響を確認します（A+B != A と B を個別に実施した場合の合計）
5. 論文に含めるアブレーションを選ぶため、これらの差分を /labrat:rebuttal のアブレーション選定に渡します

実験レポート

ユーザーがレポートまたは概要を求めた場合：

## Experiment Report

### Overview
- Total runs: N
- Date range: start to end
- Best result: [metric] = [value] (run [name])

### Results Table
| Run | Step | Config Diff | Proxy | Downstream | GPU Hours | Status |
|-----|------|-------------|-------|------------|-----------|--------|

### Key Findings
1. [Finding with evidence]
2. [Finding with evidence]

### Recommendations
1. [Next experiment to try, with justification]

上記の出力のように、結果テーブルのすべての行で同じステップに揃え、プロキシと下流を分けてください。

学習のモニタリング

定期的なモニタリングを設定します。

• 学習がまだ実行中か確認します（GPU 使用率、ログの更新状況）
• 指標の推移を追跡します
• 異常（損失の急増、NaN、OOM）を検知して通知します
• 学習の完了時に通知します

*/10 * * * * に CronCreate ジョブを作成し、{"title", "message"} JSON オブジェクトをプラグインの通知機能にパイプします。通知機能は、/labrat:setup で設定された送信先（ntfy、Slack、またはメール）に転送します。

echo "{\"title\": \"Training check\", \"message\": \"GPU util: $(nvidia-smi --query-gpu=utilization.gpu --format=csv,noheader)\"}" | ${CLAUDE_PLUGIN_ROOT}/scripts/notify.sh