reproduce

再現：論文をゼロから再現する

ML 論文を再現するには、著者が公開しなかった情報を補う必要があることがよくあります。たとえば、学習スクリプト、ハイパーパラメーター表、データ拡張の詳細、正確なデータセット分割などです。このスキルでは、「arxiv のリンクがある」状態から「論文の数値との差を測定できる再現実験を実施した」状態まで、7 つの段階を順に進めます。

概要を確認しやすくするため、各段階の詳細は references/ の個別のファイルにまとめています。

実行するタイミング

ユーザーが次のいずれかを言った場合に実行します。

• 「論文 X を再現／実装／追試／再実行したい」
• arxiv の URL を貼り、再現の意図を示した場合（「これを再現できますか」「この手法を試してみましょう」など）
• 同じ意図で OpenReview または会議録のリンクを示した場合
• 「論文にコードがないのですが、実装できますか」と言った場合

ワークフロー

段階	内容	参照先
1	論文の取得（CLI + PDF → 構造化抽出）	references/01-paper-fetch.md
2	既存コードの発見と棚卸し	references/02-code-clone.md
3	ギャップ分析（本文から不足しているハイパーパラメーターをすべて抽出）	references/03-gap-analysis.md
4	実装（uv venv、ギャップの補完、ギャップごとにコミット）	references/04-implement.md
5	データセットの取得（まず HF datasets を確認し、非公開なら代替を使用）	references/05-dataset.md
6	スモークテスト（順伝播 → 1 ステップ → 20 回の反復）	references/06-smoke.md
7	再現実験と論文で報告されたエポックでの比較	references/07-replicate.md

順番に進めてください。各段階にはそれぞれ合格基準があり、現在の段階に合格するまでは次の段階に進まないでください。

作業ディレクトリの構成

論文を再現するたびに、専用のワークスペースを用意してください。

repro/<paper-arxiv-id>/
├── paper.md              # structured extract from stage 1
├── inventory.md          # what exists / missing from stage 2
├── gaps_filled.md        # hyperparam table with provenance from stage 3
├── code/                 # implementation from stage 4 (or cloned + extended)
├── data/                 # dataset symlinks or actual data from stage 5
├── dataset_substitution.md  # if a public dataset stood in for a private one
├── smoke_logs/           # outputs from stage 6
└── results.md            # replication outcomes from stage 7

これにより、再現作業をそれぞれ独立して管理でき、後から簡単に見返せます。

相互参照

• 段階 3 の後、ギャップ分析を /labrat:paper-check スキルに渡し、論文に記載されたハイパーパラメーターを本当にすべて抽出できたか、照合します。
• 段階 4 の実装は、小さくレビューしやすい単位でコミットしてください。各コミットには、補完した値の根拠となった論文のセクションを記載します。
• 段階 6 のスモークテストが失敗した場合は、その場しのぎの修正ではなく、/labrat:debug スキルを使用します。
• 段階 7 の実行を開始する前に、複数時間に及ぶ実験を行う場合は必ず /labrat:launch チェックリストを確認します。
• 段階 7 の比較では、論文で報告されたエポックにおける比較（現在と最終の比較はしない）を /labrat:compare スキルで行います。

出力

再現ごとに、最終成果物として results.md を作成します。そこには絶対差（割合だけではなく）と、各指標に対する次の 3 つのラベルのいずれかを記載します。

• [matched within 0.X pp]：論文で報告されたばらつきの範囲内
• [gap, hypothesis: ...]：測定可能な性能低下があり、原因の仮説が示されている
• [fundamental disagreement, see X]：結果と論文の主張が一致せず、単に計算量を増やすのではなく調査が必要

ワークスペースが公開リポジトリにある場合は、プロジェクトの主要な再現追跡ドキュメントから、ワークスペースの README にリンクします。