manuscript-provenance

原稿のプロベナンス監査

パイプライン上の位置： フェーズ 2a（根拠の監査）。manuscript-typography と並行して実行します。依存関係：フェーズ 1 の修正後に内容が確定していること。manuscript-review のパス 13（要素間の整合性）で使用するマクロマニフェストを生成します。

目的

原稿が計算結果を忠実に反映していることを検証します。 文書内のすべての数値、表、図、カテゴリラベル、順序、しきい値は、 特定のスクリプト、設定ファイル、またはパイプライン出力にたどれる必要があります。 原稿への手動でのデータ入力は、再現性の欠陥です。

このスキルはプロベナンスマップを作成します。原稿内の各成果物を 生成元のコードに結び付けた構造化レポートを作成し、連鎖が途切れている箇所をすべて指摘します。

関連スキル：manuscript-review は文書を文章として監査します（構成、 論証、引用）。このスキルは、文書の内容が計算に基づいているかを監査します。 出版前の確認を網羅するには、両方を実行してください。

manuscript-review との境界に関する合意

項目	manuscript-review	このスキル（manuscript-provenance）
再現性	論文には再現に十分な説明がありますか？（§6）	コードは実際に論文の主張どおりの結果を生成しますか？（§1、§7）
図／表	判読可能で、アクセシブルで、適切に書式設定されていますか？（§12）	手入力ではなく、スクリプトで生成されていますか？（§2、§3）
レンダリングされたビジュアル	印刷時のサイズで読みやすいですか？参照箇所の近くに配置されていますか？（§23）	図の生成スクリプトは正しい形式を生成しますか？（§3）
ハイパーパラメーター	論文に根拠とともに記載されていますか？（§6）	ハードコードではなく、設定ファイルにたどれますか？（§1、§8）
コードの提供状況	論文に記述がありますか？（§17）	リポジトリ URL は有効で、README は正確で、パイプラインは動作しますか？（§11）
用語	文書内で略語の使い方は一貫していますか？（§14）	用語はコード内の識別子と一致していますか？（§5）
有効数字	文書内で精度は一貫していますか？（§12）	精度はスクリプト出力と一致していますか？（§2）
図の形式	文書の品質に適した形式ですか？（§12）	手動でエクスポートするのではなく、スクリプトで生成されていますか？（§3）
計算コスト	論文に報告されていますか？（§7）	ベンチマーク用スクリプトに値をたどれますか？（§1）
マクロと文章の整合性	挿入された値に対して、文章の枠組みは適切ですか？（§24）	値をコードにたどれますか？マクロマニフェストは生成されていますか？（§4）
要素間の一貫性	文章、キャプション、図、表は相互に整合していますか？（§24）	すべての要素は同じ実行／パイプライン出力に基づいていますか？（§9）

ルール： このスキルは文章の品質を評価しません。manuscript-review は コードベースを確認しません。利用可能な場合は、それぞれ相手のレポートを参照します。

統合ポイント — マクロマニフェスト： このスキルは §4 の監査の一環として、 次の情報を含む、マクロで挿入されたすべての値の構造化リストであるマクロマニフェスト を生成します。

• マクロ名（例：\bestf）
• 解決後の値（例：0.847）
• ソース（値を生成するスクリプトと出力ファイル）
• 原稿内の位置（ファイル、行番号、前後の文）
• 分類（TRACED / MACRO-TRACED / CONFIG-TRACED / UNTRACED / STALE）

manuscript-review のパス 13（要素間の整合性、§24）は、このマニフェストを使用して、 挿入された各値を囲む文章が、実際の数値に対して適切かを確認します。プロベナンスが確認するのは「この値は計算に基づいているか」であり、 レビューが確認するのは「この値を囲む文章は、その値の内容を踏まえて意味が通っているか」です。

対象範囲

対象範囲内：

• 原稿本文中の数値、指標、割合
• 表（内容、順序、書式）
• 図（生成スクリプト、データソース）
• LaTeX マクロ（\newcommand、\def、\pgfmathsetmacro）
• 用語、モード名、メカニズムのラベル、カテゴリ名
• 列挙、表、考察における項目の順序
• 設定値（しきい値、ハイパーパラメータ、モデル名）
• パイプラインの完全性（生データ → 最終 PDF）
• タイムスタンプの整合性（スクリプトと出力の比較）

対象範囲外：

• 文章の品質（→ manuscript-review）
• 引用の適切さ（→ manuscript-review）
• 論旨の構成（→ manuscript-review）
• コードの品質／スタイル（別途扱う項目）

入力

この監査には、次の2つの成果物が必要です。

1. 原稿のソース — LaTeX の .tex ファイル（推奨）、または代替として PDF／DOCX
2. コードベース — 原稿の内容を生成するスクリプト、設定、パイプライン

ユーザーがどちらか一方しか提供していない場合は、もう一方を依頼してください。LaTeX ソースは、コンパイル済み PDF よりも強く推奨されます。出所を監査するには、生のマークアップ、マクロ、入力コマンドを確認する必要があります。

ワークフロー

フェーズ 1 — 棚卸し

1a. 原稿成果物の抽出

すべての .tex ファイル（メインファイルと、\input／\include で取り込まれるファイル）を読み取ります。次の項目を抽出します。

• 本文中の値：文章中にそのまま記載された数値（割合、件数、指標、p 値、信頼区間、しきい値、サイズ）
• LaTeX マクロ：データ値を含むすべての \newcommand、\def、\pgfmathsetmacro、およびカスタムコマンド定義
• 表：すべての tabular／table 環境の全内容（セルの値、行／列の順序、見出し）
• 図：\includegraphics のパス、キャプションの内容、参照されているデータ
• 入力ファイル：スクリプト生成の LaTeX 断片を取り込む \input{generated/*.tex} などのパターン
• ラベルと参照：相互参照に使われる \label／\ref の組み合わせ
• 用語：本文で使われている、名前付きのモード、メカニズム、戦略、カテゴリ、手法名
• 順序付きリスト：列挙または順位付けされた項目（比較対象の手法、列挙された機能、順序付けられた結果）

原稿内のデータを含む要素すべてを、場所（ファイル、行番号）とともに並べた成果物レジストリを作成します。

1b. コードベースのマッピング

プロジェクトディレクトリをスキャンして、次を特定します。

• パイプラインのエントリーポイント：Makefile、snakemake、dvc.yaml、run.sh、main.py、または同等のオーケストレーションファイル
• 分析スクリプト：数値、表、図を生成するファイル
• 設定ファイル：config.toml、config.yaml、.env、params.yaml、ハイパーパラメータファイル
• 出力ディレクトリ：スクリプトが結果を書き込む場所（results/、output/、figures/、tables/、generated/）
• 生成された LaTeX 断片：\input で取り込むためにスクリプトが生成する、出力ディレクトリ内の .tex ファイル
• データファイル：中間結果の受け渡しに使われる CSV、JSON、HDF5、pickle

原稿の内容を生成または設定するコード成果物すべてを並べたソースレジストリを作成します。

フェーズ 2 — プロベナンスの追跡

アーティファクトレジストリの各項目について、プロベナンスチェーンの特定を試みます。原稿の値 → 生成された出力 → スクリプト → 入力データ／設定ファイルの順に追跡します。

2a. 値のプロベナンス

原稿内のすべての数値について、以下を行います。

1. スクリプトの出力（ログ、結果ファイル、生成された LaTeX）で値を検索します
2. 出力を生成するスクリプトまでさかのぼります
3. スクリプトがハードコードされた値ではなく、データ／設定ファイルを読み込んでいることを確認します
4. 完全なチェーンを記録するか、UNTRACED としてフラグを付けます

分類：

• TRACED — 原稿の値から生成コードまでの完全なチェーンがある
• MACRO-TRACED — 値が LaTeX マクロで定義され、そのマクロがスクリプトによって生成されている
• CONFIG-TRACED — 値がスクリプトによって読み込まれる設定ファイルに由来する
• UNTRACED — プロベナンスチェーンが見つからず、手動で入力されている
• STALE — プロベナンスチェーンはあるが、出力が生成スクリプトより古い

2b. 表のプロベナンス

各表について、以下を確認します。

1. 表の内容はスクリプトによって生成されていますか（CSV → LaTeX、または LaTeX の直接生成）？
2. 行／列の順序はコードによって決められていますか（指標順、アルファベット順、カテゴリ別のグループ化など）、それとも手動で配置されていますか？
3. 見出しラベルはコードで定義された名前と一致していますか？
4. 書式設定（最良値の太字、重要な数値の桁数）はコードによって適用されていますか？

分類：

• GENERATED — 表全体がスクリプトによって生成されている
• PARTIAL — 生成されたセルと手動入力のセルが混在している
• MANUAL — 生成スクリプトが見つからない
• ORDER-MANUAL — 内容は生成されているが、順序は手動で設定されている

2c. 図のプロベナンス

各図について、以下を確認します。

1. スクリプトは \includegraphics が参照するファイルそのものを生成していますか？
2. 再現性のために、スクリプトでは決定論的なシードを使用していますか？
3. スクリプト内の図の出力パスは、LaTeX の参照先と一致していますか？
4. 図のパラメーター（色、ラベル、軸の範囲）はコードで設定されていますか、それとも生成後に手動で編集されていますか？

分類：

• GENERATED — スクリプトが該当ファイルを生成している
• POST-EDITED — スクリプトが元の図を生成しているが、手動編集が検出された（例：Illustrator のメタデータ、スクリプトの出力とのチェックサムの違い）
• MANUAL — 生成スクリプトが見つからない
• STALE — 図ファイルの生成後に生成スクリプトが変更されている

2d. 用語のプロベナンス

名前付きのモード、メカニズム、カテゴリ、メソッドラベルについて、以下を確認します。

1. 用語はコードで定義されていますか（列挙型、定数、設定キー、クラス名）？
2. 原稿内の用語はコード内の用語と完全に一致していますか？
3. 原稿で表示用の名前が使われている場合、コードまたは設定ファイルに明示的なマッピングがありますか？

分類：

• CODE-DEFINED — 用語がコードの定義と一致している
• MAPPED — コードから表示名への明示的なマッピングがある
• UNMAPPED — 用語が原稿にはあるが、コードにはない
• INCONSISTENT — 用語が原稿とコードの両方にあるが、一致していない（例：コードでは greedy_search となっている一方、原稿では箇所によって「Greedy Search」と「greedy approach」が使われている）

2e. 順序のプロベナンス

各順序付きリスト、ランキング比較、順序を伴う列挙について、以下を確認します。

1. コードによって順序が決められていますか（指標順、アルファベット順、列挙型の順序など）？
2. 原稿の順序は、コードによって決められた順序と一致していますか？
3. 原稿のリストにコードの出力にない項目が含まれていたり、その逆があったりしますか？

分類：

• CODE-ORDERED — 順序がコードの出力と一致している
• MANUAL-ORDER — 順序がコードの出力と異なる、またはコードに順序決定のロジックがない
• SUBSET-MISMATCH — 原稿に記載された項目が、コードの出力と異なる

フェーズ 3 — インフラストラクチャの監査

3a. LaTeX マクロの適切な管理

• データを保持するマクロはすべて、プリアンブルに手入力するのではなく、スクリプトで生成する必要があります
• 検出するパターン：.tex ファイル内で直接定義されている \newcommand{\someMetric}{42.7}（不適切）と、スクリプトの出力ファイルである generated/metrics.tex を読み込む \input{generated/metrics.tex}（適切）
• 値がスクリプトの出力に一切含まれていないマクロにフラグを立てます
• 数値やデータの値を保持する、メインの .tex ファイル内で定義されたマクロにフラグを立てます

3b. パイプラインの完全性

• 単一のコマンドで、生データから原稿のすべての成果物を再生成できますか？
• パイプラインは文書化されていますか（Makefile、README、CI 設定）？
• 中間ステップはキャッシュされますか、それとも毎回すべて再実行する必要がありますか？
• 再現性を確保するため、乱数シードは固定されていますか？
• ソフトウェアのバージョンは固定されていますか（requirements.txt、environment.yml、ロックファイル）？

3c. 設定とコードの分離

• ハイパーパラメーター、しきい値、モデル名は設定ファイルに記述されていますか？
• ファイルパスは相対パス（移植可能）ですか、それとも絶対パス（壊れやすい）ですか？
• コミット済みのコードに、認証情報、API キー、マシン固有のパスが含まれていませんか？
• 設定の単一のエントリーポイントがありますか、それとも設定がスクリプト間に散在していますか？

3d. 古い出力の検出

• 更新日時を比較します：スクリプトとその出力ファイル
• 生成元のスクリプトより古い出力（古くなった出力）にフラグを立てます
• 対応するスクリプトがない出力（孤立した出力）にフラグを立てます
• 対応する出力がないスクリプト（未使用のコード、または未実行のコード）にフラグを立てます

3e. バージョンの固定

• 依存関係はロックされていますか（バージョンを指定した requirements.txt、conda environment.yml、poetry.lock、package-lock.json）？
• データのバージョンは追跡されていますか（DVC、git-lfs、データチェックサム）？
• 原稿はコードとともにバージョン管理されていますか（同じリポジトリ、タグ付きリリース）？

フェーズ 4 — 相互参照とマニフェストの生成

4a. マクロマニフェストの生成

マクロマニフェスト（manuscript-review への主要な引き継ぎ成果物）を生成します。フェーズ 1a で特定し、フェーズ 2a で追跡した、データを保持するすべてのマクロについて、以下を記載します。

Macro: \bestf
Value: 0.847
Source: results/metrics.json → scripts/generate_latex_macros.py → generated/metrics.tex
Locations:
  - paper.tex:142 — "achieving an F1 score of \bestf{}"
  - paper.tex:287 — "The \bestf{} result represents a substantial improvement"
  - abstract.tex:8 — "...with \bestf{} F1 score"
Classification: MACRO-TRACED

さらに、フェーズ 1a で見つかった、データ（指標、件数、パラメーター）を保持する単独の数値（マクロではないもの）もすべて含めます。これらはマクロにするべきですが、そうなっていない値です。

Bare value: 50
Location: paper.tex:198 — "convergence after 50 epochs"
Should-be-macro: YES — this is a training parameter, should trace to config
Classification: UNTRACED (no macro, no provenance)

マニフェストを [manuscript-name]-macro-manifest.json として、来歴レポートと同じ場所に保存します。このファイルは manuscript-review の Pass 13（要素間の一貫性）で使用され、文章と値の適切さを検証します。

4b. manuscript-review との相互参照

この原稿の manuscript-review レポートが存在する場合は、読み込んで以下を行います。

• 追跡不能な値を manuscript-review の §6（方法論）および §7（結果）の所見に対応付けます。来歴の欠落は、再現性に関する懸念と同時に生じることがよくあります
• 用語の不一致を、manuscript-review フレームワークにおける §14（略語）または §15（表記法）の問題の可能性としてフラグを立てます
• 優先度の高い来歴上の問題を、§6／§7 の不備として報告します
• マクロマニフェストを manuscript-review の §24（要素間の一貫性）の所見に反映します。マクロの値に対して、周辺の文章で不適切な定性的表現（14.3% に対する「わずか」、0.3% に対する「劇的」など）を使っている場合は、§24 の不備です

manuscript-review レポートが存在しない場合は、補完的な監査としてその実行を推奨し、Pass 13 で利用できるマクロマニフェストがあることを記載します。

フェーズ 5 — レポートの生成

references/checklist.md と references/report-template.md を読み込みます。

Read references/checklist.md
Read references/report-template.md

テンプレートの構成に従って、来歴レポートを生成します。

1. 来歴の概要 — 総合スコア、カテゴリ別の内訳
2. 来歴マップ — 各原稿成果物とその出典の対応
3. 不備一覧 — 追跡不能、古い、手動、一貫性なしの各所見
4. インフラストラクチャの評価 — パイプライン、設定、バージョン管理の状況
5. 修正項目一覧 — 優先順位付きの修正
6. チェックリストの状況 — チェックポイントごとの合格／不合格を含むチェックリスト全体

フェーズ 6 — 出力

原稿ディレクトリに次の 2 つのファイルを保存します。

1. [manuscript-name]-provenance-report.md — 完全なプロベナンスレポート
2. [manuscript-name]-macro-manifest.json — manuscript-review Pass 13 で使用する構造化マクロマニフェスト

マクロマニフェストの JSON 構造：

{
  "macros": [
    {
      "name": "\\bestf",
      "value": "0.847",
      "source_chain": "results/metrics.json → scripts/gen_macros.py → generated/metrics.tex",
      "locations": [
        {
          "file": "paper.tex",
          "line": 142,
          "context": "achieving an F1 score of \\bestf{}"
        },
        {
          "file": "paper.tex",
          "line": 287,
          "context": "The \\bestf{} result represents a substantial improvement"
        }
      ],
      "classification": "MACRO-TRACED"
    }
  ],
  "bare_numbers": [
    {
      "value": "50",
      "location": {
        "file": "paper.tex",
        "line": 198,
        "context": "convergence after 50 epochs"
      },
      "section": "methodology",
      "should_be_macro": true,
      "rationale": "Training parameter — should trace to config",
      "classification": "UNTRACED"
    }
  ]
}

ユーザーに次の内容を提示します。

• プロベナンスのカバー率（TRACED / 成果物の合計数）
• 重大度別の UNTRACED / STALE / MANUAL の検出数
• マクロにすべき裸の数値の数
• 優先度の高い是正措置 5 件
• パイプラインの完全性に関する判定
• macro manifest が manuscript-review Pass 13 で利用可能である旨の注記

重大度の分類

• CRITICAL — 原稿内の値にプロベナンスチェーンがなく、かつ重要な結果である（主な知見、要旨の指標、表の見出しとなる数値）。つまり、論文の中心的な主張をコードから検証できません。

• HIGH — 値／表／図のプロベナンスが追跡できない、または古く、結果または方法論のセクションに掲載されている。再現性に欠落があります。

• MEDIUM — 用語の不一致、手作業での並べ替え、表の部分的な生成、スクリプトへの設定値のハードコード。保守性と一貫性にリスクがあります。

• LOW — 軽微な問題：表示名のマッピングがないものの用語の違いは小さい、生成スクリプトのない重要度の低い図、生成された図への見た目だけの手作業による修正。

基本原則

• 二値のプロベナンス。 各成果物は、追跡可能か、追跡不可能かのどちらかです。「部分的に再現可能」という状態はありません。部分的であれば、破綻しています。

• コードが真実です。 原稿とコードの内容が一致しない場合、原稿が誤りであることが証明されるまでは、原稿が誤りです。不一致を指摘し、原稿の著者がコードの出力を「意図的に」上書きしたと決めつけないでください。

• マジックナンバーよりマクロ。 LaTeX 内のすべてのデータ値はマクロにしてください。すべてのマクロは生成される必要があります。「明らか」な値であっても例外はありません。

• パイプラインは証拠です。 make（または同等のコマンド）で生データから PDF を生成できない場合、その原稿は再現可能ではありません。部分的なパイプラインは部分的な評価にとどまり、合格にはなりません。

• 設定はコードではありません。 ハイパーパラメーター、しきい値、モデル名、ファイルパスはすべて、スクリプト本文に散在させず、設定ファイルに記述してください。

• 順序はデータです。 表や列挙項目の順序は、ひとつの主張です。著者の「見栄えがよい」という感覚ではなく、コード（ソート順、列挙型の定義）に基づく必要があります。

• タイムスタンプは重要です。 昨日スクリプトが変更されているのに、図が先月生成されたものであれば、疑わしい状態です。古い出力はプロベナンスの不備です。

• 置き換えではなく、補完です。 この監査では計算上の根拠を確認します。manuscript-review では文書の品質を確認します。どちらも必要であり、互いを包含するものではありません。

呼び出しパターンの例

ユーザーが次のいずれかを言った場合：

• 「プロベナンスを確認して」
• 「数値はコードに基づいていますか」
• 「パイプラインを監査して」
• 「再現性を検証して」
• 「原稿をスクリプトと照合して」
• 「プロベナンス監査」
• 「表は生成されていますか」
• 「図はスクリプトから生成されていますか」
• 「/manuscript-provenance」

これらはすべて、このスキルを起動します。