reproduce

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

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

概要を見やすく保つため、各ステージに対応するリファレンスファイルを references/ 以下に用意しています。

実行するタイミング

ユーザーが次のいずれかを言ったとき：

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

ワークフロー

ステージ	内容	リファレンス
1	論文の取得（arxiv HTML → 構造化された抽出）	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 の後、ギャップ分析を paper-verification スキルに渡し、論文に記載されたハイパーパラメーターをすべて本当に捉えられているか、照合してください。
• ステージ 4 の実装は、小さくレビューしやすい単位でコミットしてください。各コミットには、補完した値の根拠となった論文の節を記載します。
• ステージ 6 のスモーク実行で失敗した場合は、その場しのぎで修正せず、/phd-skills:debug スキルに回してください。
• ステージ 7 の実行は、数時間に及ぶ実行を開始する前に、/phd-skills:launch のチェックリストに従ってください。
• ステージ 7 の比較は、論文で報告されたエポック時点で /phd-skills:compare スキルに従って行ってください（現在の結果と最終結果を比較してはいけません）。

出力

再現実験ごとに、最終成果物は results.md です。そこには絶対差分（％だけではありません）と、各指標に対する次の 3 種類のラベルのいずれかを記載します。

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

ワークスペースが公開リポジトリにある場合は、プロジェクトの再現実験追跡用メインドキュメントから、ワークスペースの README にリンクしてください。