experiment-design-planner

実験設計プランナー

研究上の主張を、その主張に実際に答えられる実験計画に落とし込みます。このスキルは実験の実施前に計画を立てるためのものであり、完了した結果を報告するためのものではありません。

次の場合にこのスキルを使用します。

• ユーザーが新しい実験やアブレーションを実施しようとしている
• 論文の主張を裏付ける証拠が必要である
• ベースライン、指標、対照条件、データセットが明確でない
• ユーザーが一度に多くの変数を変更しようとしている
• あいまいな実行でクラスタや計算時間を浪費したくない
• 投稿前に査読者を納得させられる証拠が必要である

このスキルは、次のスキルと組み合わせて使用します。

• 実験計画をプロジェクトレベルの証拠、リスク、アクションの記録にする場合は、research-project-memory
• 設計が整い、実行に移す場合は、run-experiment
• 結果が得られた後は、experiment-report-writer
• 証拠が査読者を納得させられるか検証する場合は、paper-reviewer-simulator
• ベースラインの選択、公平性、または査読者を納得させられる比較について、より詳細な検討が必要な場合は、実験マトリクスを確定する前に baseline-selection-audit
• グラフや表の結果が得られ、主張を裏付けているか確認する場合は、figure-results-review

スキルディレクトリの構成

<installed-skill-dir>/
├── SKILL.md
└── references/
    ├── ablation-matrix.md
    ├── evidence-standards.md
    ├── metrics-and-controls.md
    └── report-template.md

段階的な読み込み

• 必ず references/evidence-standards.md と references/metrics-and-controls.md を読みます。
• 計画でバリアント、コンポーネント、ベースライン、ハイパーパラメーター、データセット、またはモデルサイズを比較する場合は、references/ablation-matrix.md を読みます。
• 実験計画を保存する場合、または内容の充実した計画を返す場合は、references/report-template.md を使用します。
• 対象のリポジトリに memory/ がある場合は、research-project-memory の規約に従って、予定している証拠、実験の系統、リスク、アクションを更新します。
• 実験が最新のベースライン、ベンチマーク、またはリーダーボードの慣例に依存する場合は、ウェブ検索で最新の情報源を確認します。

基本原則

• コマンドラインではなく、主張から始めます。
• 実験を実施する前に仮説を明示します。
• 新しい手法を導入する前にベースラインを使います。
• 実験が明示的に要因計画である場合を除き、一度に変更する変数は1つにします。
• 結果を解釈する前に、対照条件と交絡変数を定義します。
• 反証条件と代替策を定義し、否定的な結果も役立つものにします。
• 実験を実施する前に、表や図を設計します。
• 停止条件も重要です。次に進むのに十分な結果を事前に決めます。

ステップ 1 - 主張と問いを定義する

次の項目を抽出します。

• 論文またはプロジェクトの主張
• 研究課題
• 対象読者：内部デバッグ、アドバイザーへの報告、論文の証拠、反論への対応、ベンチマークに関する主張
• 期待する出力：Markdown の計画、LaTeX の実験セクションのアウトライン、実行マトリクス、または保存するファイル
• 実験モード：
  • single：対照条件を設定した1つの比較
  • ablation：コンポーネントまたは変数の切り分け
  • benchmark：データセットやタスクをまたいだ手法の比較
  • theory：理論的予測を裏付ける実証的な証拠
  • diagnostic：失敗の原因や予想外の結果を把握する

あいまいな目標を、検証可能な問いに書き換えます。

Vague: Does our method work?
Testable: Does component X improve metric M over baseline B on datasets D1/D2 under the same training budget?

ステップ 2 - 仮説を明示する

次の項目を書きます。

• 主仮説
• 代替説明
• 指標に期待する変化の方向と、おおよその効果量
• 反証条件
• 判断基準

ユーザーが反証条件を示せない場合、その実験を始める準備はできていません。

ステップ 3 - 証拠の基準を定める

references/evidence-standards.md を読みます。

必要な証拠を決めます。

• 1つの表、1つの曲線、1つのアブレーション、1つの定性的な例、1つの定理に沿った診断、またはベンチマーク一式
• データセット／タスクの数
• シード数または反復数
• 必要なベースライン
• 許容できる分散
• 統計的検定または信頼区間が必要かどうか
• 結果が論文の主張を裏付ける必要があるか、次の手順を決めるためだけのものか

ステップ 4 - ベースラインと対照条件を選ぶ

次の項目を特定します。

• 主ベースライン
• 関連する場合は、最も強力な先行手法または現在のSOTA
• 単純なベースライン
• アブレーション用ベースライン
• 必要に応じて、オラクルまたは上限値
• 制御する変数
• 交絡変数

ベースラインがない場合は、最初の実験をベースライン確立のための実験にします。

ステップ 5 - 指標とロギングを選ぶ

references/metrics-and-controls.md を読みます。

各指標について、以下を指定します。

• 定義
• 方向性
• 集約方法
• 分割方法
• 分散の報告方法
• 失敗の解釈
• その指標が問いに答える理由

必要なロギングを定義します。

• コマンド
• 設定ファイルのパス
• git コミット
• データセットのバージョン
• シード
• ハイパーパラメーター
• ハードウェア／ランタイム
• 指標
• 成果物：表、図、チェックポイント、ログ

ステップ 6 - 実行マトリクスを作成する

実行が複数ある場合は、references/ablation-matrix.md を読みます。

次の項目を含む実行テーブルを作成します。

• 実行 ID
• 変更する変数
• 固定する制御条件
• データセット／分割
• 指標
• シード／反復回数
• 期待される結果
• 状態
• 出力パス

1 回の実行で概念上の変数が複数変更される場合は、実験を分割します。

ステップ 7 - 停止条件と次の判断を定義する

以下を記述します。

• 主張を裏付けるのに十分な結果
• 主張を反証する、または弱める結果
• 別のアブレーションを実施するきっかけとなる結果
• 停止して執筆／報告に移ることを示す結果
• 計算予算の上限
• 期限の制約

ステップ 8 - 査読者のリスクを確認する

最終決定の前に、以下を確認します。

• 査読者から、ベースラインが弱いと指摘される可能性はありませんか？
• 比較は公平ですか？
• シード／反復回数は十分ですか？
• 実験によって、主張するメカニズムを切り分けられていますか？
• 指標は主張に沿っていますか？
• 結果を説明し得る交絡因子はありませんか？
• 否定的な結果からも何かを学べますか？

回答から重大な弱点が明らかになった場合は、実行前に設計を更新します。

ステップ 9 - 実験計画を作成する

references/report-template.md を使用します。

プロジェクトに保存する場合、パスが指定されていなければ、次を使用します。

docs/experiments/experiment_plan_YYYY-MM-DD_<short-name>.md

init-python-project / new-workspace で作成したコードリポジトリまたはコードワークツリー内で作業する場合は、次を優先します。

docs/reports/experiment_plan_YYYY-MM-DD_<short-name>.md

最終計画は run-experiment で実行でき、後から experiment-report-writer で報告できるものにします。

ステップ 10 - プロジェクトメモリに書き戻す

プロジェクトで research-project-memory を使用している場合は、以下を更新します。

• memory/evidence-board.md：計画中の EVD-### 項目と EXP-### 実験ファミリー
• memory/provenance-board.md：計画中のソースクラス、想定される CSV／レポート出力、判明している場合は集約要件
• memory/claim-board.md：関連する主張を紐付け、planned、evidence-needed、provisional の各状態を正確に付与
• memory/risk-board.md：設計で明らかになったベースライン、メカニズム、指標、シード、計算、査読者に関するリスク
• memory/action-board.md：最初にどの実験を開始するかを含む、実行可能な次のアクション
• memory/handoff-board.md：計画が実行可能になったら、run-experiment への引き継ぎを準備
• memory/phase-dashboard.md：進行中の実験設計またはエビデンス作成のゲートを更新
• 関連するワークツリーの .agent/worktree-status.md：ブランチ／ワークツリーが関係する場合は、実験の目的と終了条件

未実行の実験には planned 状態を使用します。期待される結果を、観測済みのエビデンスとして記録しないでください。

最終確認

最終決定の前に、以下を確認します。

• 主張と仮説が明示されている
• ベースラインが定義されている
• 独立変数が切り分けられている
• 制御条件と外乱変数が列挙されている
• 指標が問いに結び付いている
• 実行マトリクスが具体的である
• 再現に十分なロギング要件がある
• 停止条件と判断ルールが明示されている
• 査読者のリスクが記載されている
• リポジトリに memory/ がある場合は、プロジェクトメモリが更新されている