experiment-bridge

ワークフロー 1.5：実験ブリッジ

各レビュアーの担当枠の前に、選択可能なレビュアーに従ってください： 呼び出しを解決 → .aris/reviewer.json → Claude Code のデフォルト（Codex MCP） を、標準のヘルパーリゾルバーを通じて reviewer_route.py で指定し、この 担当枠のティア、新しいコンテキスト、ソース／画像入力、決定論的なゲートを維持します。 以下の Codex の例／固定設定は backend=codex にのみ適用されます。他のルートでは、 それぞれの初回呼び出し／応答の契約に従います。ルートと実際に返された ID を保存してください。 選択したレビュアーを利用できない場合は REVIEW_UNAVAILABLE とします。実際の ファミリー／完了状況／スコープに基づいて合否を判定してください。呼び出し時の レビュアー／モデル／エフォートのオーバーライドを、レビュアーを含む子プロセスに渡します。 生成ワーカーに変更はありません。

計画に基づいて実験を実装し、デプロイします：$ARGUMENTS

概要

このスキルは、ワークフロー 1（アイデアの発見＋手法の洗練）とワークフロー 2（自動レビューループ）をつなぎます。実験計画を受け取り、初期結果が得られるよう、実行中の実験に落とし込みます。

Workflow 1 output:                    This skill:                                    Workflow 2 input:
refine-logs/EXPERIMENT_PLAN.md   →   implement → GPT-6-Astra review → deploy → collect → initial results ready
refine-logs/EXPERIMENT_TRACKER.md     code        (cross-model)    /run-experiment     for /auto-review-loop
refine-logs/FINAL_PROPOSAL.md

定数

• CODE_REVIEW = true — デプロイ前に、GPT-6-Astra xhigh が実験コードをレビューします。GPU 時間を無駄にする前にロジックのバグを検出します。スキップするには false に設定します。
• AUTO_DEPLOY = true — 実装とレビューの後、実験を自動的にデプロイします。デプロイ前にコードを手動で確認するには false に設定します。
• SANITY_FIRST = true — 残りを開始する前に、サニティステージの実験（最小かつ最速）を実行します。セットアップのバグを早期に検出します。
• MAX_PARALLEL_RUNS = 4 — 並列でデプロイする実験の最大数（利用可能な GPU 数に制限されます）。
• BASE_REPO = false — ベースコードベースとして使用する GitHub リポジトリの URL。設定すると、まずリポジトリをクローンし、その上に実験を実装します。false（デフォルト）の場合は、コードを一から記述するか、既存のプロジェクトファイルを再利用します。
• COMPACT = false — true の場合、（1）利用可能であれば idea-stage/IDEA_REPORT.md 全体の代わりに idea-stage/IDEA_CANDIDATES.md を読み、（2）結果の収集後に実験結果を EXPERIMENT_LOG.md に追記します。

オーバーライド：/experiment-bridge "EXPERIMENT_PLAN.md" — compact: true, base repo: https://github.com/org/project

入力

このスキルでは、次のいずれか、または複数を使用します。

1. refine-logs/EXPERIMENT_PLAN.md（最適）— /experiment-plan による、主張を軸にした実験ロードマップ
2. refine-logs/EXPERIMENT_TRACKER.md — 実行単位の進捗表
3. refine-logs/FINAL_PROPOSAL.md — 実装のコンテキストとなる手法の説明
4. idea-stage/IDEA_CANDIDATES.md — 簡潔なアイデアの概要（COMPACT: true の場合に推奨） (見つからない場合は ./IDEA_CANDIDATES.md にフォールバックします)
5. idea-stage/IDEA_REPORT.md — ブレインストーミングの全出力 (見つからない場合は ./IDEA_REPORT.md にフォールバックします)

どれも存在しない場合は、実装する実験をユーザーに尋ねます。

ワークフロー

フェーズ 1：実験計画の解析

EXPERIMENT_PLAN.md を読み、次の内容を抽出します。

1. 実行順序とマイルストーン — どの実験を先に実行するか（サニティ → ベースライン → メイン → アブレーション → 仕上げ）
2. 各実験ブロックについて：
   • データセット／分割／タスク
   • 比較するシステムとバリアント
   • 算出する指標
   • セットアップの詳細（バックボーン、ハイパーパラメーター、シード）
   • 成功基準
   • 優先度（必須実行か、あると望ましいか）
3. 計算予算 — GPU 時間の推定合計
4. 手法の詳細 — FINAL_PROPOSAL.md に基づく、実装する内容の詳細

簡潔な概要を提示します。

📋 Experiment plan loaded:
- Milestones: [N] (sanity → baseline → main → ablation)
- Must-run experiments: [N]
- Nice-to-have: [N]
- Estimated GPU-hours: [X]

Proceeding to implementation.

研究契約へのフォールバック：idea-stage/docs/research_contract.md がまだ 存在しない場合（/idea-discovery 以外でアイデアが選ばれた場合、または以前の実行の場合）は、 選択したアイデアと実験計画の主張を使い、templates/RESEARCH_CONTRACT_TEMPLATE.md から 今すぐ作成してください。後続の /result-to-claim と /ablation-planner はこのファイルを主張の情報源として読み込み、セッション復旧 （docs/SESSION_RECOVERY_GUIDE.md）にもこのファイルの存在が必要です。

Phase 2: 実験コードの実装

BASE_REPO が設定されている場合 — まずリポジトリをクローンします。

git clone <BASE_REPO> base_repo/
# Read the repo's README, understand its structure, find entry points
# Implement experiments by modifying/extending this codebase

各マイルストーンについて、順番に実験スクリプトを作成します。

1. 既存のコードを確認する — プロジェクト（またはクローンした base_repo/）を調べ、既存の実験スクリプト、モデルコード、データローダーを確認します。可能な限り再利用してください。

2. 不足している部分を実装する：

   • 適切な argparse を使ったトレーニングスクリプト（すべてのハイパーパラメーターを設定可能にする）
   • 指定されたメトリクスを計算する評価スクリプト
   • 必要に応じたデータの読み込み／前処理
   • まだ実装されていない場合のベースライン実装
   • 再現性を確保するための固定乱数シード
   • 後で分析できるよう、結果を JSON/CSV に保存
   • 適切なロギング（CLAUDE.md で設定されている場合は wandb）

3. 計画に記載された実行順序に従う — まず健全性チェック段階の実験を実装し、次にベースライン、その後に主要手法、最後にアブレーションを実装します。

4. デプロイ前にセルフレビューする：

   • EXPERIMENT_PLAN.md のすべてのハイパーパラメーターが argparse に反映されていますか？
   • 乱数シードは固定され、制御可能ですか？
   • 結果は解析可能な形式（JSON/CSV）で保存されていますか？
   • コードは FINAL_PROPOSAL.md の手法の説明と一致していますか？

Phase 2.5: モデル間コードレビュー（CODE_REVIEW = true の場合）

CODE_REVIEW が false の場合は、この手順をスキップしてください。

デプロイ前に、実験コードを GPT-6-Astra xhigh に送ってレビューしてもらいます。

まずこのレビュースロットを解決してください。以下は backend=codex の例です。

mcp__codex__codex:
  model: gpt-6-astra
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    Review the following experiment implementation for correctness.

    ## Experiment Plan:
    [paste key sections from EXPERIMENT_PLAN.md]

    ## Method Description:
    [paste from FINAL_PROPOSAL.md]

    ## Implementation:
    [paste the experiment scripts]

    Check for:
    1. Does the code correctly implement the method described in the proposal?
    2. Are all hyperparameters from the plan reflected in the code?
    3. Are there any logic bugs (wrong loss function, incorrect data split, missing eval)?
    4. Is the evaluation metric computed correctly?
    5. **CRITICAL: Does evaluation use the dataset's actual ground truth labels — NOT another model's output as ground truth?** This is a common and severe bug.
    6. Any potential issues (OOM risk, numerical instability, missing seeds)?

    For each issue found, specify: CRITICAL / MAJOR / MINOR and the exact fix.

    === SCOPE LIMITS (these bound what you PROPOSE, never what you look for) ===
    Report anything that is actually wrong here — including a rare-looking case, if
    this repo actually produces it. Then keep the fix in scope:
    1. This is a RESEARCH-WORKFLOW tool, not a security paper. Verification is
       welcome; over-defense is not. Assume a cooperating operator on their own
       machine — a malicious local user is NOT in the threat model.
    2. Do NOT propose SHA / hash / content-fingerprint / digest-binding schemes.
       Reporting a real defect in hashing code that already exists is fine.
    3. NO speculative machinery: do not add feature flags, migration frameworks,
       compat layers, wrappers, pins, or similar mechanisms unless evidence shows
       a current repo defect they fix or an explicit existing invariant they must
       preserve. "Load-bearing", "compatibility", and "not scaffolding" are labels,
       not evidence. Point to the failing path/artifact or invariant, and check the
       proposal's factual premises, such as whether a named package version exists.
    4. NO corner-case obsession: exotic encodings, symlink races, RTL text and
       millisecond races are out of scope unless you can show the case arises here.
    5. Where a rubric or checklist is genuinely needed, do not over-mechanize
       judgement. A clear sentence a human reads beats a scored table nobody
       maintains.
    Exception: code that runs remote commands, starts a network service, or installs
    an MCP server runs on the user's machine with their credentials — trust-boundary
    findings there are in scope and the default is strict.
    Say plainly when something is correct. Do not manufacture findings.

レビュー結果に応じた対応：

• CRITICAL の問題がない → Phase 3 に進みます
• CRITICAL の問題が見つかった → 修正してからレビューを再依頼します（最大 2 回）
• Codex MCP が利用できない → 何もせずにスキップし、Phase 3 に進みます（正常に縮退）

フェーズ 3：健全性チェック（SANITY_FIRST = true の場合）

実験スイート全体をデプロイする前に、健全性チェック段階の実験を実行します。

/run-experiment [sanity experiment command]

完了するまで待ちます。次の点を確認します。

• トレーニングループがエラーなく実行される
• メトリクスが正しく計算され、保存される
• GPU メモリの使用量が上限内に収まっている
• 出力形式が期待どおりである

健全性チェックに失敗した場合 → あきらめる前に自動デバッグします。予算：同じ失敗に対するパッチ試行を最大 2 回、その後、クリーンな再実装を最大 2 回（合計 4 回）：

1. エラーを読む — トレースバック、stderr、ログファイルを解析します。（意外な REVIEWER 判定に対しても、主要なアーティファクトを読むという同じ規律を適用します。shared-references/review-tracing.md § トレースを使ったデバッグ を参照してください。）
2. 診断する — 失敗を分類します。
   • OOM → バッチサイズを減らすか、勾配チェックポイントを有効にします
   • ImportError → 不足しているパッケージをインストールします
   • FileNotFoundError → パスを修正するか、データをダウンロードします
   • CUDA error → GPU が利用可能か確認し、モデルサイズを減らします
   • NaN／発散 → 学習率を下げ、データの前処理を確認します
3. 修正して再実行する — 修正を適用し、健全性チェックを再実行します
4. 2 回目以降も失敗する場合 → Codex に救援を求めます（Codex プラグインがインストールされている場合）： 次の再試行の前に /codex:rescue を実行し、根本原因について別の意見を求めます。Codex はコードとエラーログを独自に読み取るため、Claude が見落とした問題（テンソル形状の誤り、見つけにくいインポートのシャドーイング、設定の不一致など）に気付くことがあります。提案された修正を適用し、再実行します。
   • /codex:rescue を利用できない場合（プラグインがインストールされていない場合）は、Claude による診断を続けます
5. 同じ失敗に対してパッチ試行が 2 回とも失敗した場合 → 破棄してクリーンに再実装します （再実装は最大 2 回）。失敗したスクリプトを EXPERIMENT_PLAN.md／研究契約に基づいて書き直すことは、最後の手段ではなく、別のパッチに進む PEER の対応です。間違ったパッチを 2 回重ねたうえで 3 回目のパッチを当てるよりも、クリーンに作り直すほうが通常は望ましいです。その試行で生成したコード／スキャフォールディング（このフェーズで生成したスクリプト）のみを削除します。計画、EXPERIMENT_TRACKER.md、ユーザーが作成したプロジェクトソース、収集したデータ、結果は決して削除できません（shared-references/external-cadence.md § 壊れた試行はパッチだけでなく、再スタートさせる を参照してください）。
6. 予算を使い切った（パッチ 2 回＋再実装 2 回）、または 2 回の再実装で同じ方法で失敗した場合は？ → 中止し、試した修正とエラーログをすべて添えて失敗を報告します。クリーンな再実装が 2 回とも同じように失敗する場合、通常は計画か環境に問題があります。報告ではそれを明記してください。人の対応が必要なのは、壊れたビルド自体ではなく、その問題です。壊れたコードで続行してはいけません。

最初の失敗であきらめてはいけません。実験のクラッシュのほとんどは、人の介入なしに修正できます。

フェーズ 4：実験全体をデプロイする

計画のマイルストーン順に従って実験をデプロイします。ジョブ数に応じて振り分けます。

小規模バッチ（マイルストーンあたり 5 ジョブ以下） → /run-experiment を直接使用します。

/run-experiment [experiment commands]

大規模バッチ（10 ジョブ以上、複数シードのスイープ、またはフェーズ間の依存関係あり） → 適切にオーケストレーションするため、/experiment-queue を使用します。

/experiment-queue [grid spec or manifest]

自動振り分けルール：EXPERIMENT_PLAN.md のいずれかのマイルストーンで、10 ジョブ以上が宣言されている場合（例：seeds: [42, 200, 201, ...] × N: [64, 128, 256] × n: [50K, 150K, 500K, 652K] = 36 ジョブ）、または teacher→student のフェーズ依存関係が宣言されている場合、そのマイルストーンは /experiment-queue に振り分けます。それ以外は /run-experiment を使用します。

/experiment-queue は、OOM を考慮したバックオフ付き再試行、古い画面のクリーンアップ、ウェーブ遷移時の競合防止、フェーズ依存関係の強制、クラッシュに強い queue_state.json への状態永続化を追加します。マニフェストの YAML 形式については、skills/experiment-queue/SKILL.md を参照してください。

各マイルストーンについて：

1. 実験を並列でデプロイします（/run-experiment では最大 MAX_PARALLEL_RUNS、/experiment-queue ではマニフェストの max_parallel まで）
2. /monitor-experiment を使って進捗を追跡します（/experiment-queue が動作中の場合は queue_state.json を読み取ります）
3. 実験が完了したら結果を収集します

🚦 チェックポイント（AUTO_DEPLOY = false の場合）：

🔧 Code implementation complete. Ready to deploy:

Milestone 0 (sanity): [status — passed/pending]
Milestone 1 (baseline): [N experiments, ~X GPU-hours]
Milestone 2 (main method): [N experiments, ~X GPU-hours]
Milestone 3 (ablations): [N experiments, ~X GPU-hours]

Total estimated: ~X GPU-hours on [N] GPUs

Deploy now? Or review the code first?

フェーズ 5：初期結果を収集する

実験が完了したら、次の手順を実行します。

1. 出力ファイルを解析する（JSON/CSV/ログ）し、主要な指標を確認します
2. トレーニング品質を確認する — W&B データを利用できる場合（CLAUDE.md に wandb: true と wandb_project がある場合）は、/training-check を呼び出して NaN、損失の発散、停滞、過学習を検出します。W&B が設定されていない場合は、何もせずにスキップします。
3. refine-logs/EXPERIMENT_TRACKER.md を更新する — Status 列と Notes 列を記入します
4. EXPERIMENT_PLAN.md の成功基準を確認します — 各実験は基準を満たしましたか？
5. 初期結果の要約を作成する：

# Initial Experiment Results

**Date**: [today]
**Plan**: refine-logs/EXPERIMENT_PLAN.md

## Results by Milestone

### M0: Sanity — PASSED
- [result]

### M1: Baselines
| Run | System | Key Metric | Status |
|-----|--------|-----------|--------|
| R001 | baseline_1 | X.XX | DONE |

### M2: Main Method
| Run | System | Key Metric | Status |
|-----|--------|-----------|--------|
| R003 | our_method | X.XX | DONE |

### M3: Ablations
...

## Summary
- [X/Y] must-run experiments completed
- Main result: [positive/negative/inconclusive]
- Ready for /auto-review-loop: [YES/NO]

## Next Step
→ /auto-review-loop "[topic]"

フェーズ 5.5：簡潔なログを作成する（COMPACT = true の場合）

COMPACT が false の場合は、すべてスキップします。

完了した実験をそれぞれ EXPERIMENT_LOG.md に追記します。

## [Run ID] — [timestamp]
- **System**: [method name]
- **Config**: [key hyperparameters]
- **Result**: [primary metric = X.XX]
- **Verdict**: [positive / negative / inconclusive]
- **Reproduce**: `python train.py --config configs/run_id.yaml --seed 42`

この構造化ログはセッションの復旧後も保持されます。後続のスキルは、画面出力を解析する代わりにこのログを読み取ります。

フェーズ 5.6：アブレーション計画を自動作成する

主な実験（M2）が良好な結果で完了したら、/ablation-planner を呼び出してアブレーション研究を設計します。

• 主な結果と手法の説明を読み取ります
• 主張に基づくアブレーション計画を作成します。どのコンポーネントを取り除くか、何を比較するか、どのような結果を予想するかを定めます
• アブレーション項目を refine-logs/EXPERIMENT_PLAN.md と refine-logs/EXPERIMENT_TRACKER.md に追記します
• 主な結果が否定的、または決定的でない場合は、アブレーション計画をスキップし、要約にその旨を記載します

/ablation-planner を利用できない場合は、何もせずにスキップします。既存の EXPERIMENT_PLAN.md のアブレーション項目（存在する場合）は変更しません。

フェーズ 6：引き継ぎ

最終ステータスを提示します。

🔬 Experiment bridge complete:
- Implemented: [N] experiment scripts
- Deployed: [N] experiments on [M] GPUs
- Completed: [X/Y] must-run, [A/B] nice-to-have
- Main result: [one sentence]

Results: refine-logs/EXPERIMENT_RESULTS.md
Tracker: refine-logs/EXPERIMENT_TRACKER.md

Ready for Workflow 2:
→ /auto-review-loop "[topic]"

出力プロトコル

すべての出力ファイルに、次の共有プロトコルを適用します。

• 出力バージョニングプロトコル — まずタイムスタンプ付きファイルを書き込み、その後、固定名のファイルにコピーします
• 出力マニフェストプロトコル — すべての出力を MANIFEST.md に記録します
• 出力言語プロトコル — プロジェクトの言語設定に従います

主なルール

• 重大 — 評価にはデータセットの正解ラベルを使用してください。 評価スクリプトを作成する際は、モデルの予測をデータセットの実際の正解ラベル／ターゲットと必ず比較してください。別のモデルの出力を正解として使用してはいけません。次の点を再確認してください。（1）正解ラベルはベースライン／バックボーンモデルからではなく、データセットの分割から取得すること。（2）すべての手法について、同じ正解ラベルを基準に評価指標を計算すること。（3）タスクに公式の評価スクリプトがある場合は、それを使用すること。
• 計画に従ってください。 EXPERIMENT_PLAN.md にない実験を考案してはいけません。何かが欠けていると思われる場合は、その旨を記録し、追加はしないでください。
• まず健全性を確認してください。 健全性チェック段階に合格することを確認せずに、実験一式を実行してはいけません。
• 既存のコードを再利用してください。 新しいスクリプトを書く前に、プロジェクトを調査してください。重複させず、既存のコードを拡張してください。
• すべて JSON/CSV として保存してください。 自動レビューループには、ターミナル出力だけでなく、解析可能な結果が必要です。
• トラッカーを更新してください。 EXPERIMENT_TRACKER.md には、各実行の完了後に実際のステータスを反映してください。
• いつまでも待たないでください。 実験に見積もり時間の 2 倍を超えてもかかる場合は、その旨を明記して次のマイルストーンに進んでください。
• 予算を把握してください。 計画の予算に対する GPU 使用時間を追跡してください。上限に近づいている場合は警告してください。
• Vast.ai のライフサイクル。 vast.ai インスタンスを使用する場合は、すべての実験が完了し、結果をダウンロードした後にインスタンスを破棄してください。実行中のインスタンスは毎秒課金されるため、アイドル状態のまま放置しないでください。完了したら /vast-gpu destroy または /vast-gpu destroy-all を使用してください。
• Modal のライフサイクル。 gpu: modal を使用する場合、Modal は実行ごとに自動でスケールゼロになるため、クリーンアップは不要です。ただし、実行前に必ず費用の見積もりを提示し、https://modal.com/settings で支出上限が設定されていることを確認してください（CLI 経由では絶対に設定しないでください）。

他のスキルとの組み合わせ

/idea-discovery "direction"          ← Workflow 1: find + refine + plan
/experiment-bridge                   ← you are here (Workflow 1.5: implement + deploy)
/auto-review-loop "topic"            ← Workflow 2: review + iterate
/paper-writing "NARRATIVE_REPORT.md" ← Workflow 3: write the paper

Or use /research-pipeline for the full end-to-end flow (includes this bridge).