experiment-report-writer

実験レポート作成

実験の証拠を、実験を再実行しなくても読者が評価できる明確な研究レポートにまとめます。

このスキルは、単独のドキュメント、論文やラボノートの一節、メンター向けの進捗報告、プレゼンテーション用の実験概要を作成する際に使用してください。

完了した結果をプロジェクトの主張、証拠、リスク、アクション、図、またはワークツリーの判断に反映する場合は、このスキルとresearch-project-memoryを併用してください。

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

<installed-skill-dir>/
├── SKILL.md
└── templates/
    └── experiment-report.md

段階的な読み込み

• レポートを保存する場合は、templates/experiment-report.mdをデフォルトのMarkdownのひな形として使用してください。
• ユーザーがチャットでの草稿だけを求めている場合は、テンプレートをそのまま読むかコピーする必要はありませんが、同じセクションの順序に従ってください。

基本原則

• すべての主張を、設定、コマンド、ログ、指標、表、図、コミットハッシュ、またはユーザーから提供されたメモなどの証拠に基づかせてください。
• 観測された結果と解釈を分けてください。仮説を測定済みの事実として示してはいけません。
• 別の研究者が何を実行したのか特定できる程度に、再現可能なレポートを作成してください。
• 数値を列挙する前に、実験が重要である理由を説明してください。
• 適切な比較対象を選んでください。ベースライン、前回の実行、アブレーションの対照、期待される挙動、または公表済みの数値などです。
• 不確実性をそのまま示してください。証拠が不足している場合は、不足していることを明記し、最小限必要な確認事項を尋ねてください。
• 対象読者に合わせて書いてください。ラボノートは詳細でも構いませんが、メンター向けの報告では、判断、証拠、次のステップを重視してください。

ステップ 1 - レポートの分類

レポートの形式を特定してください。

• single-experiment：1回の実行、または1つの統制された比較
• ablation-report：1つの要因を検証する複数のバリエーション
• batch-summary：スイープまたは実験バッチから得られた複数の関連実行
• mentor-update：判断に役立つ議論を含む簡潔な進捗報告
• paper-section：論文の一部となることを想定した、洗練された文章

また、以下も特定してください。

• 対象読者
• 出力形式：Markdown、LaTeX、スライドのアウトライン、またはチャット用草稿
• ユーザーがファイルを希望する場合は保存先
• 想定される長さ
• 図、表、設定、ログ、またはノートブックが利用可能かどうか

ユーザーが形式を指定していない場合は、Markdownをデフォルトとして使用してください。ファイルを希望していて保存先の指定がない場合は、次を使用してください。

docs/reports/experiment_report_YYYY-MM-DD.md

ステップ 2 - 証拠の収集

記憶よりも一次証拠を優先してください。

以下を確認してください。

• 実験コマンドまたはスクリプト
• 設定ファイルとパラメーターの上書き
• ランダムシードと実行回数
• データセット名、分割、前処理、サンプル数
• モデル、手法のバリエーション、チェックポイント、またはアルゴリズムのバージョン
• 関連する場合はハードウェアと実行時間
• 指標、ログ、結果の表、図、失敗例
• 利用可能な場合は、Gitのコミットハッシュまたはコードのバージョン

役立つローカルでの確認方法は次のとおりです。

git rev-parse --short HEAD
find . -maxdepth 3 -type f \( -name "*.yaml" -o -name "*.yml" -o -name "*.json" -o -name "*.csv" -o -name "*.md" \)
find . -maxdepth 4 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.pdf" -o -name "*.svg" \)

ユーザーが非公式なメモだけを提供している場合は、それを使用しつつ、再現性に関する不足情報を明示してください。

ステップ 3 - 実験の経緯を整理する

草稿を作成する前に、実験を次の項目に整理してください。

• 問い：この実験で何を明らかにしようとしましたか？
• 動機：なぜその問いが重要ですか？
• 仮説：何を、なぜ予想しましたか？
• 手法：ベースラインと比べて何を変更しましたか？
• 統制条件：何を固定しましたか？
• 測定：どの指標が問いへの回答に役立ちますか？
• 結果：何が起きましたか？
• 解釈：結果から何が示唆されますか？
• 判断：次に何をすべきですか？

アブレーションやスイープでは、独立変数を明確にし、公平な比較を維持してください。

必須レポート構成

ユーザーから別の形式を求められない限り、次のセクションを使用してください。

# [Experiment Report Title]

## Summary
## 1. Experiment Motivation
## 2. Experiment Setup
## 3. Core Algorithm or Method
## 4. Metrics
## 5. Results
## 6. How to Read the Figures
## 7. Interpretation
## 8. Conclusion and Discussion
## 9. Limitations and Caveats
## 10. Next Steps
## Reproducibility Notes

中心となるアルゴリズムがない場合は、「該当なし」と記載し、代わりに実験がデータ、ハイパーパラメーター、評価、インフラストラクチャ、または分析のどれを変更するのかを簡潔に説明してください。

図がない場合は、「図の読み方」を省略してください。表が主な証拠である場合は、代わりに「表の読み方」を設けてください。

セクションごとのガイダンス

概要

以下を含む箇条書きを3～6項目作成してください。

• 実験の問い
• 特に重要な設定の詳細
• 主な結果
• 解釈
• 推奨される次のステップ

1. 実験の動機

実験を行う研究上またはエンジニアリング上の理由を説明します。

• 検証する問題
• 期待されるメカニズム
• 結果がプロジェクトに影響する理由
• 実験によって裏付ける意思決定

2. 実験の設定

実行を再現または監査するのに十分な詳細を記載します。

• データセット、分割、前処理
• ベースラインと比較するバリエーション
• 主要なハイパーパラメーターとパラメーターの変更
• 学習・評価コマンド、設定ファイル、または実行 ID
• 乱数シードと試行回数
• 該当する場合は、ハードウェア、実行時間、コードのバージョン

重要な設定が5つを超える場合は、パラメーターを表にまとめます。

3. 中核となるアルゴリズムまたは手法

実験を理解するのに必要な範囲で、アルゴリズムを説明します。

• 受け取る入力
• 生成する出力
• 主要な手順または目的
• ベースラインからの新しい点や相違点
• 解釈に影響する計算量、前提条件、実装の詳細

読者にとって必要でない限り、一般的な背景を詳しく説明しすぎないでください。

4. 指標

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

• 定義
• 方向：値が大きいほど良い、小さいほど良い、または目標範囲
• 単位
• 集計方法：平均、中央値、最良のチェックポイント、最終エポック、信頼区間、標準偏差
• 実験の問いに関連する理由

指標同士が相反する可能性がある場合は、その旨を明記します。

5. 結果

解釈より先に結果を提示します。

以下を使用します。

• 正確な数値の比較には表
• 傾向、分布、定性的な例には図
• 主な差分には短い説明文

常にベースラインを明示し、可能な場合は絶対値と意味のある差分を報告します。

6. 図の読み方

各図について、以下を説明します。

• 図が示す目的
• x軸：変数、単位、尺度
• y軸：指標、単位、方向
• 凡例：手法名、グループ、色、マーカー、線種
• エラーバーや網掛け領域がある場合はその内容
• 点が個別の実行、平均、チェックポイント、エポック、サンプルのいずれを示すか
• 読者が注目すべき主な視覚的パターン

軸が対数スケール、正規化済み、クリップ済み、または単位なしの場合は、その旨を明記します。

7. 解釈

観察された結果を実験の動機と関連付けます。

• 仮説が裏付けられたかどうか
• ベースラインと比べて何が変わったか
• 考えられる説明
• 別の説明の可能性
• 予想外の結果や否定的な結果
• 対応を決めるのに十分な証拠があるかどうか

シードが1つしかない場合、統計的な根拠が弱い場合、または対照条件が欠けている場合は、断定を避けた表現を使います。

8. 結論と考察

実用上の結論を述べます。

• 何が分かったか
• どの意思決定を裏付けるか
• 手法を継続、却下、または追加検証するか
• 結果がプロジェクト全体にどう影響するか

9. 制約と注意点

結論を変える可能性のあるリスクを記載します。

• シードの数が少ない
• データセットやサブセットが限定的
• ベースラインがない
• 学習が不安定
• 実装にバグがある可能性
• 指標の不一致
• データ漏洩や評価データの汚染リスク
• ハードウェアや実行時間の制約

10. 次のステップ

具体的なフォローアップを提案します。

• すぐに行う検証を1つ
• 価値の高い拡張を1つ
• 必要に応じて整理または文書化の作業を1つ

各ステップが、解消する不確実性とどう結び付くかを示します。

プロジェクトメモリへの書き戻し

プロジェクトで research-project-memory を使用している場合、レポートの草稿を作成した後に結果を書き戻します。

• memory/evidence-board.md：完了した EVD-### の概要、ソースのパス、関連付けられた主張 ID、制約、不確実性
• memory/provenance-board.md：実行ポインター、CSV、レポート、集計ルール、論文で使用する候補から、ソースからエビデンスまでの追跡可能性
• memory/claim-board.md：関連する主張を、supported、weakened、revised、evidence-needed、provisional、cut などのライフサイクルに沿って移行
• memory/risk-board.md：軽減済みのリスクをクローズするか、結果によって明らかになった新たなリスクを追加
• memory/action-board.md：再実行、執筆、手法の改訂、保留、打ち切りの判断など、レポートに基づく次のステップ
• memory/handoff-board.md：結果が paper-result-asset-builder、paper-evidence-board、result-diagnosis、または執筆に進める状態になったら、引き継ぎを作成
• memory/phase-dashboard.md：プロジェクトがエビデンスの作成、論文用アセットの作成、草稿作成に進んだ場合、または結果によって主張が弱まり、フェーズが後退した場合に、現在のゲートを更新
• ワークツリーの .agent/worktree-status.md の「Local Hot Results」：コードワークツリーで作業する場合は、結果を必ず最初にここへ記録します。進行中および中間段階の結果を書き込む既定の場所です。
• <ProjectRoot>/memory/hot-results.md：結果が確認済みで、プロジェクトの上位 5～7 件に入り、プロジェクトレベルの主張を直接変える場合に限り、ここへ移します。進行中の作業やワークツリー内にとどまる作業の結果は、ここに書き込まないでください。
• memory/current-status.md：最新の信頼できる実験状況と、次のセッションの開始地点

解釈を測定事実として記述しないでください。ログや表にある指標には observed、説明には inferred を使用します。

出力品質チェックリスト

最終化する前に、次の項目を確認します。

• レポートに実験の問いと意思決定の背景が記載されている
• 主要なパラメーターとベースラインがすべて明示されている
• 指標に方向と単位が含まれている
• 結果と解釈が区別されている
• すべての図表に読み取り方の説明がある
• 不足しているエビデンスにラベルが付けられ、創作されていない
• 結論がデータの範囲を超えて主張していない
• 次のステップが実行可能な内容になっている
• 該当する場合、プロジェクトメモリが更新されている