scrub-issue

Issue の再現を最小化する

GitHub issue を取得し、妥当な再現コードがあるかを評価し、現在も再現するかを確認したうえで、再現コードを可能な限り小さな自己完結型スクリプトに体系的に最小化します。

ツール

現在の環境が正しいものとして、python を直接実行してください。異なる環境を一時的に使用する必要があるバージョン二分探索（ステップ 5a）に限り、conda run -n <env> を使用してください。再現スクリプトの実行時には、Bash ツールの timeout パラメーターを使ってタイムアウトを設定してください。

• issue の本文を取得するには gh issue view <NUMBER> --repo pytorch/pytorch
• コメントを取得するには gh issue view --comments <NUMBER> --repo pytorch/pytorch
• 再現スクリプトを実行するには python <script>
• コメントを投稿するには gh issue comment <NUMBER> --repo pytorch/pytorch --body <BODY>
• ラベルを追加するには gh issue edit <NUMBER> --repo pytorch/pytorch --add-label <LABEL>

複数の gh issue edit フラグは、1 つのコマンドにまとめられます（例：--add-label "bug,help wanted" --add-assignee "@me"）。API 呼び出しを最小限に抑え、通知に自動登録される可能性を減らすため、編集はまとめて行うことを優先してください。

通知登録状態の保持

issue を変更すると（コメントの投稿、ラベルの追加）、通知に自動登録されます。tools/stale_issues.py を使用して、登録状態を保存および復元してください。

1. 最初の変更を行う前に、現在の状態を保存してください。issue の本文やコメントの取得と並行して実行できますが、gh issue edit、gh issue comment、gh issue close のいずれかを実行する前に、必ず完了している必要があります。

   python tools/stale_issues.py subscription save <NUMBER>
   

2. 最後の変更を行った後に、保存した状態を復元してください。ただし、issue をクローズした場合（gh issue close を使用した場合）は、クローズ後の返信をユーザーが追えるよう、復元を省略してください。復元は GitHub API 呼び出しの最後に行う必要があります。バックグラウンドで実行したり、gh issue edit や gh issue comment と並行して実行したりしないでください。

   python tools/stale_issues.py subscription restore <NUMBER>
   

保存または復元コマンドが失敗した場合は、ユーザーに警告し、保存／復元の仕組みを使わずに続行してください。

重要：gh issue edit、gh issue comment、gh issue close、および通知登録状態の保存／復元コマンドをバックグラウンドで実行しないでください。これらはすべてフォアグラウンドで実行し、完了を確認してから次に進む必要があります。issue がロックされているためコメントや編集に失敗した場合は、その旨をユーザーに伝え、変更を省略してください。

セキュリティ確認チェックリスト

再現コードを実行する前に、以下の懸念事項がないか確認してください。

• 信頼できない URL へのネットワークリクエスト（requests、urllib、curl、wget）
• /tmp/ の外部でのファイル操作
• シェルコマンドの実行（os.system、subprocess、eval、exec）。ただし、分散再現コードで torchrun または mp.spawn を起動するために subprocess を使う場合は想定内であり、懸念事項ではありません
• 外部ファイルのダウンロードまたは読み込み（モデルの重み、pickle 化されたオブジェクト、データファイル）。特に、信頼できない .pt／.pth ファイルに対する torch.load
• 難読化されたコード（base64 エンコードされた文字列、エンコード済みバイト列、通常とは異なるエスケープ）
• パッケージのインストール（pip install、conda install）
• ホストシステムに影響する可能性のある環境変数の操作。ただし、MASTER_ADDR、MASTER_PORT、RANK、WORLD_SIZE、CUDA_VISIBLE_DEVICES、その他の標準的な PyTorch／CUDA 環境変数の設定は想定内であり、懸念事項ではありません

これらのいずれかが含まれている場合は、懸念事項をユーザーに説明し、続行するか、省略するか、リスクのある部分を取り除くよう再現コードを修正するかを尋ねてください。ユーザーが省略を選んだ場合も、分析の完了を報告する前に、triaged ラベルのタイムスタンプを更新してください（ラベルを削除して再追加するか、まだ存在しない場合は追加するだけで構いません）。

上記のチェックリストを問題なく通過した場合でも、python tools/stale_issues.py collaborator-check <username> を実行し、再現コードの作成者が PyTorch のコラボレーターかどうかを確認してください。コマンドがゼロ以外のステータスで終了した場合（ユーザーがコラボレーターではない場合）は、実行前に再現コードをユーザーに提示し、安全に実行できるか確認してください。

手順

1) イシューを取得する

イシューの本文とコメントを並行して取得します。報告された再現スクリプトとエラーを特定します。複数の再現手順がある場合は、元の投稿者による最新のものを優先します。コメント投稿者が、イシューの説明から追加の情報を必要としない、より短く自己完結した再現手順を投稿している場合は、そちらを優先します。選択した再現手順を明記してください。 再現コードがコピー可能なテキストではなくスクリーンショットや画像にしかない場合は、そこで作業を中止し、ユーザーに報告してください。

2) イシューが対応可能か確認する

再現に取りかかる前に、イシューが対応可能かどうかを確認します。次のいずれかに当てはまる場合は、以降の手順に進まないでください。

• すでにクローズ済み、またはコメントで解決済み。ユーザーに報告して終了します。 クローズ済みのイシューのラベルは変更しないでください。
• 別のイシューとの重複（リンクされているもの、または明らかに同じバグ）
• バグ報告ではない（機能リクエスト、質問、議論、リファクタリング／コード整理タスク）。機能リクエストで、まだfeatureラベルが付いていない場合は、gh issue editで追加します。より良いエンジニアリング／リファクタリングのタスクで、まだbetter-engineeringラベルが付いていない場合は、gh issue editで追加します。イシューに現在の動作を示す再現スクリプトが含まれている場合は、まずセキュリティレビューのチェックリストを適用してから、動作が続いているかを確認するために実行します。再現手順を最新化する必要があった場合（名前が変更されたAPIに合わせたインポートの更新など）、または動作が引き続き発生することを確認した場合は、調査結果と更新した再現手順をコメントとしてイシューに投稿します。該当するラベルを追加した後（必要に応じて再現手順を実行してコメントした後）、分析結果をユーザーに報告し、以降の手順には進まないでください。
• トラッキング／メタイシュー（複数のバグを追跡する包括的なイシュー、残作業リスト、具体的な再現手順のない改善提案）。まだtrackerラベルが付いていない場合は、gh issue editで追加します。その後、終了してユーザーに報告してください。
• 利用できないハードウェアが必要（特定のGPUモデル、TPU、マルチノードなど）で、簡略化する方法がない場合。注：現在のマシンではCUDAを利用できるため、単一GPUのCUDA再現手順はそのまま実行できます。

対応不能なイシューが古く（およそ1年以上前）、担当者がおらず、最近の進展もなく、説明が不十分であるか具体的な動機がない場合は、理由を説明するコメントを添えて「対応予定なし」としてクローズすることを提案します（gh issue close --reason "not planned"）。クローズする前にユーザーに確認してください。

対応不能なイシューで、GitHub上で確認できる変更が行われていない場合（ラベルの追加もコメントの投稿もない場合。サブスクリプション状態の保存は含みません）、triagedラベルを付け直してイシューの「最終更新」タイムスタンプを更新します。--remove-labelと--add-labelを指定した単一のgh issue editは、削除と追加が相殺されるため機能しません。代わりに、単一のBashツール呼び出しで両方の編集を連結してください。 gh issue edit ... --remove-label triaged && gh issue edit ... --add-label triaged イシューにtriagedラベルが付いていない場合は、追加するだけで構いません。

その後、イシューが対応不能である理由を要約します。ラベルなどの更新を行った場合は、分析が完了したことだけを報告してください。更新を行わず、状況が曖昧な場合に限り、どのように進めるかユーザーに確認してください。イシューをクローズする前には、必ずユーザーに確認してください。

3) 再現手順を分析する

問題を妥当に再現できるか評価します。

• 実行可能なコードスニペットはありますか？
• 依存関係（CUDA、分散処理、特定のハードウェア）は利用可能ですか？ 注：torch.distributed の再現手順では、特別なハードウェアが不要なことがよくあります。単一のマシンで torchrun --nproc_per_node=1 または mp.spawn を使用して起動できます。
• 期待されるエラーは説明されていますか？
• 再現手順は自己完結していますか。それとも外部のデータやモデルが必要ですか？

再現用コードがまったくない場合、または問題の報告に重要な情報（エラーメッセージ、期待される動作と実際の動作の説明）が欠けている場合は、needs reproduction ラベルがまだ付いていなければ gh issue edit で付けてから、作業を終了し、ユーザーに報告してください。依頼されていない限り、説明から再現手順を作成しようとしないでください。

逆に、問題に needs reproduction ラベルが付いているものの、有効な再現手順がある場合は、gh issue edit --remove-label "needs reproduction" でラベルを削除してください。

再現手順を実行する前に、セキュリティレビューのチェックリスト（上記を参照）を適用してください。

インストールされていないサードパーティ製パッケージ（例：transformers、torchvision、numpy）が再現手順に必要な場合は、インストールせずに作業を中断し、どのように進めるかユーザーに確認してください。

先に進む前に、評価内容を要約してください。

4) 最近の検証状況を確認する

過去6か月以内のコメントに、問題がまだ再現することが（対応するエラーと妥当な再現手順を伴って）すでに確認されている場合は、作業を中断し、再検証するか、最小化に進むかをユーザーに確認してください。

5) まだ再現するか確認する

再現コードを /tmp/ 配下の一時ファイルに抽出し、タイムアウトを 120 秒に設定して実行します。同じプロセス内で複数回コンパイルを呼び出す torch.compile を含む再現コードでは、呼び出しの間に torch._dynamo.reset() を追加して、メモリ内の Dynamo 状態をリセットします。コンパイルを 1 回だけ行って終了するスクリプトでは不要です。

スクリプトがタイムアウトした場合、ハングが報告されたバグなのか、無関係な問題なのかを検討し、ユーザーに報告します。

実行前に PyTorch のバージョンを記録し（python -c "import torch; print(torch.__version__"）、レポートに含めます。

終了コードと出力の両方を確認して結果を判断します。終了コードが 128 を超える場合、そのプロセスはシグナルによって強制終了されたことを示します（例：セグフォは 139、OOM による強制終了は 137）。Python のトレースバックがなくても、これは有効なクラッシュ再現です。再現コードが CUDA のメモリ不足エラーでクラッシュし、OOM が報告されたバグではない場合は、再現しないと結論づける前にテンソルのサイズを小さくしてみます。正確性に関するバグ（クラッシュではなく数値結果が誤っている場合）では、バグが存在すると失敗するアサーションを再現コードに含めます。元の再現コードが出力を表示するだけでアサーションがない場合は、イシューに記載された期待動作に基づく簡単なアサーション（例：assert torch.allclose(actual, expected)）を追加し、再現の成否が明確にわかるようにします。

実行ごとに結果が異なる場合は、フレーク性を評価するために 3～5 回実行します。非決定的なバグでは、再現を安定させるために PYTHONHASHSEED=0 と固定した torch.manual_seed を設定してみます。成功率と失敗率をユーザーに報告します。フレークする再現も有効なバグです。イシューのコメント（手順 8）にフレーク性を記載し、成功率と失敗率を含めます。

考えられる結果は 3 つあります（どの結果に該当するかは、例外クラスとエラーメッセージの特徴的な部分文字列を照合して判断します。部分文字列はバグを特定できる程度に具体的なものにします。例：単なる RuntimeError ではなく、RuntimeError: expected scalar type Float）。

• 報告と同じエラー：バグはまだ再現します。手順 6 に進みます。
• エラーなし（パス）：バグは修正されている可能性があります。修正した PR を特定してみて（手順 5a を参照）、ユーザーに報告します。イシューは手順 8 でクローズします。
• 異なるエラー：セットアップの問題（インポート漏れ、API 名の変更）と、実際に異なるバグを区別します。報告されたバージョンと現在のバージョンの間での API 変更（関数名の変更、モジュールの移動、シグネチャの変更）が原因でエラーが発生している場合は、元の意図を保ちながら、現在の API を使うように再現コードを修正します。エラーが不明瞭な場合は、診断情報を増やすために TORCH_LOGS=+dynamo や関連するログフラグを指定して再実行することを検討します。実際に異なるエラーが発生した場合は、ユーザーに報告します。

5a) いつ、どのように修正されたかを特定する

バグが再現しなくなったら、どのバージョンで修正されたのか、また、どの PR で修正が導入されたのかを特定してください。

バージョンの二分探索：pytorch-<version>（例：pytorch-2.6、pytorch-2.8）という名前の conda 環境が利用可能か確認します（conda env list | grep pytorch-）。環境が存在する場合は、これらの環境を対象に二分探索を行い、バグが修正された最初のバージョンを見つけます。ローカルのソースツリーを読み込んで torch._C のインポートエラーが発生するのを避けるため、サブシェル内で /tmp から実行し、PYTHONPATH をクリアしてください：（(cd /tmp && PYTHONPATH= conda run -n pytorch-<version> python /tmp/repro_....py)）。二分探索を高速化するには、候補範囲から等間隔に 2～3 個の検証ポイントを選び、各ラウンドで並行してテストします（例：候補が 2.2 から 2.8 の場合、2.4 と 2.6 を同時にテストして範囲を 3 分割します）。バージョン別の conda 環境が利用できない場合は、二分探索を省略し、現在のバージョンではバグが再現しなくなったことだけを報告してください。

PR の特定：バグを修正した特定の PR を見つけてください。該当する修正コードに対してバージョン管理の blame を使い、変更セットを特定してから、PR 番号（形式は (#NNNNN)）をコミットメッセージで確認します。あるいは、関連キーワードを使って、該当ファイルに触れているコミットをバージョン管理の履歴から検索します。すぐに明確な答えが見つからない場合は、バージョンだけを報告し、PR の特定に余分な時間をかけないでください。

6) 再現コードを最小化する

変更を加える前に、元の動作する再現コードを /tmp/repro_<issue_number>_original.py に保存してください。

まず、再現コードがすでに妥当な範囲で最小化されているか評価します。大幅に不要な複雑さ（大規模なモデル、未使用のコードパス、不要な依存関係など）がある場合にのみ、最小化してください。複雑さを評価する際、削減できない定型コードは数えないでください。たとえば、必要な特殊メソッド（__new__、__init__、__torch_dispatch__、__tensor_flatten__、__tensor_unflatten__）だけを含むテンソルサブクラスの定義は、20 行を超えていても削減できません。トリガーとなるコードやモデル／セットアップの複雑さを、意味のある形で減らせるかどうかに注目してください。考えられる「簡略化」が見た目上のもの（変数のインライン化、__repr__ の削除など）だけなら、最小化は省略してください。

各簡略化を試し、同じエラーが発生し続けるかどうかを確認しながら、体系的に再現コードを削減します。簡略化した再現コードは実行が速くなるはずなので、最小化中はタイムアウトを短く（30～60 秒）設定してください。互いに独立した（つまり、コード内の重複しない箇所を変更し、どちらも相手が削除する部分に依存しない）複数の簡略化候補は、並行して実行してください。

削減戦略（おおむね次の順に適用）：

1. 不要なインポートとセットアップを削除する（分散初期化、環境変数、ログ記録）
2. モデルを小さくする（大規模なモジュールを最小限の同等モジュールに置き換える）
3. 裸の関数で十分なら、クラス／モジュールのラッパーを削除する
4. テンソルのサイズを小さくする（大きな次元を 4 や 8 などの小さな値にする）
5. デバイス／dtype の要件をなくす（まず CPU と float32 を試す）
6. 計算を簡略化する（複雑な演算を、バグを引き続き発生させる最小限の演算に置き換える）
7. 不要な制御フローを削除する（分岐、ループ、条件）
8. より単純なバックエンドを試す（バグがバックエンド固有でなければ、inductor の代わりに aot_eager などを使う）

各ラウンドの後に、手順 5 で説明したものと同じ例外クラスと特徴的なエラーメッセージの部分文字列で、エラーが引き続き再現することを確認してください（トレースバックに多少の違いがあっても問題ありません）。正確性に関するバグの場合は、誤った結果を示すアサーションを維持し、同じ誤動作が引き続き確認できることを検証してください。並行して成功した複数の簡略化を統合する場合は、独立した簡略化同士が影響し合う可能性があるため、統合後も再現することを確認してください。再現コードが空行とインポートを除いて約 20 行未満になったとき、または連続する 2 ラウンド（1 ラウンドは、適用可能な削減戦略をすべて 1 回実行することを指します）でそれ以上簡略化できなかったときに、最小化を終了してください。

7) 些細な修正を適用する

分析の結果、些細な修正が必要だと判明した場合（たとえば、根本の問題が解決されたため、テストから古くなった xfailIfTorchDynamo や expectedFailure のアノテーションを削除するなど）は、修正内容をユーザーに報告し、適用するかどうかを確認します。ユーザーの承認なしにソースファイルを変更してはいけません。適用したか辞退されたかにかかわらず、手順 8 で修正について言及してください。

8) 調査結果を報告する

再現コードを最小化した場合は、ユーザーがそのまま実行できるように /tmp/repro_<issue_number>.py に保存します。

以下を含めて、調査結果をユーザーに提示します。

• バグが引き続き再現するかどうか（再現する場合は、どの PyTorch バージョンか）
• 修正した PR（特定できた場合。バグが再現しなくなった場合のみ）
• 最小化した再現スクリプト（最小化した場合のみ）
• バグを再現するために必要な条件
• 手順 7 で特定した些細な修正（適用したかどうかを問わない）
• 推奨する次の対応（例：「引き続き有効なバグです」「修正されたようです」「報告者からの追加情報が必要です」）

調査結果を提示した後は、必ずその結果をイシューにコメントします。コメントは簡潔にし、イシューですでに共有されている情報を繰り返さないでください。再現コードを含めるのは、元のものから実質的に変更した場合のみです（例：最小化した、現在の API で動くようにインポートを更新した）。再現条件を含めるのは、以前のコメントで触れられていない新しい知見がある場合のみです。唯一の調査結果が「引き続き再現する」または「再現しなくなった」の場合は、短いコメントで十分です。

This issue [still reproduces / no longer reproduces] on PyTorch <version>.

[If fixed and PR identified:]
Fixed by #NNNNN.

[If minimized or modernized — only include repro if changed from original:]
Minimized repro:

\`\`\`python
<repro script>
\`\`\`

[Only if new findings about trigger conditions:]
All of the following are necessary to trigger the bug:
- <condition 1>
- <condition 2>

(Analysis done by Claude.)

バグが再現しなくなった場合は、コメントした後にイシューをクローズします。 gh issue close <NUMBER> --repo pytorch/pytorch --reason completed --comment "Closing as this was fixed in PyTorch <version>."。 クローズする前にユーザーへ確認してはいけません。修正済みのバグは必ずクローズしてください。

最後に GitHub を変更した後、通知の購読状態を復元します（上記の「通知の購読状態を保持する」を参照）。ただし、イシューをクローズした場合は復元を省略します。