triaging-issues

PyTorch Issue Triage Skill

此 Skill 協助進行 GitHub issue 分流，包含路由分派 issue、標註標籤以及留下第一線回覆。

Contents

• 可用的 MCP 工具
• 絕對不能新增的標籤
• Issue 分流步驟
  • 步驟 0：已完成路由 — 跳過
  • 步驟 1：提問 vs Bug/新功能
  • 步驟 1.5：需要重現步驟 — 外部檔案
  • 步驟 2：移轉 Issue
  • 步驟 2.5：PT2 Issue — 特殊處理
  • 步驟 3：重定向至次要值班團隊（Secondary Oncall）
  • 步驟 4：標註 Issue 標籤
  • 步驟 5：高優先級 — 需要人工審查
  • 步驟 6：bot-triaged（自動）
  • 步驟 7：標記為已分流（Mark Triaged）
• V1 限制

標籤參考： 請參閱 labels.json 了解適合分流的完整標籤目錄。請僅使用存在於此檔案中的標籤。 切勿自行發明或猜測標籤名稱。此檔案已排除 CI 觸發器、測試設定、版本說明（release notes）、廢棄標籤（deprecated labels）以及需要人工決策的標籤。

PT2 分流指南： 分流 PT2/torch.compile issue 時，請參閱 pt2-triage-rubric.md 取得詳細的標籤標註指引。

回覆範本： 標準回覆訊息請參閱 templates.json。

---

MCP Tools Available

分流時請使用以下 GitHub MCP 工具：

工具	用途
mcp__github__issue_read	取得 issue 詳細資訊、留言及現有標籤
mcp__github__issue_write	標註標籤或關閉 issue
mcp__github__add_issue_comment	新增留言（僅用於重定向提問型 issue）
mcp__github__search_issues	搜尋類似 issue 以取得上下文資訊

---

Labels You Must NEVER Add

前綴／類別	原因
未在 labels.json 中的標籤	僅能套用白名單中存在的標籤
ciflow/*	僅供 PR 使用的 CI 工作流觸發器
test-config/*	僅供 PR 使用的測試套件選擇器
release notes: *	用於版本說明，系統自動指派
ci-*, ci:*	CI 基礎設施控制
sev*	嚴重程度標籤需由人工決策
merge blocking	需由人工決策
actionable, needs design, needs reproduction, needs research	預留給人工審查者完成評估後使用
包含 "deprecated" 的任何標籤	已廢棄
oncall: releng	非分流重定向目標。請改用 module: ci

若被阻擋： 當 Hook 阻擋某個標籤時，僅新增 triage review 並停止操作。後續將由人工處理。

這些規則由 PreToolUse hook 強制執行，該 hook 會對照 labels.json 驗證所有標籤。

絕不覆蓋人工標籤

如果人工審查者已經標註了標籤（特別是 ci: sev、嚴重程度標籤或優先級標籤），請勿移除或替換它們。你的職責是補充標籤，而非覆蓋。

---

Issue Triage (for each issue)

0) 已完成路由 — 跳過

如果 issue 已經帶有任何 oncall: 標籤，請直接完全跳過。 切勿：

• 新增任何標籤
• 新增 triaged
• 留下留言
• 進行任何分流工作

該 issue 已歸屬於子值班團隊（sub-oncall team），他們會自行負責其佇列。

1) 提問 vs Bug/新功能

• 若為單純提問（非 bug 報告或功能需求）：關閉 issue 並使用 templates.json 中的 redirect_to_forum 範本。
• 若無法確定是 bug/功能需求還是提問：使用 request_more_info 範本要求提供更多資訊並停止操作。

1.5) 外部檔案

檢查 issue 內文是否包含需要使用者下載才能重現的外部檔案連結。

需偵測的模式：

• 夾帶檔案：.zip、.pt、.pth、.pkl、.safetensors、.onnx、.bin 等檔案
• 外部雲端硬碟：Google Drive、Dropbox、OneDrive、Mega、WeTransfer 等連結
• 模型庫：指向 Hugging Face Hub 模型檔案的連結

處置方式：

1. 編輯 issue 內文以移除／遮蔽下載連結
   • 替換為：[Link removed - external file downloads are not permitted for security reasons]
2. 使用 templates.json 中的 request_self_contained_reproduction 範本
3. 請勿新增 triaged 標籤 — 待使用者提供可自包含的重現範例

1.55) 缺失重現步驟 — 其他情況

遇到以下情況時，請要求提供自包含的重現步驟（self-contained reproduction）並停止操作：

• 使用者回報特定硬體問題（例如特定的 GPU 型號），但未提供自包含的重現指令稿
• 使用者提及特定的模型／檢查點（checkpoint）／資料集，且無法在數行程式碼內公開執行
• issue 描述了版本升級導致的破壞性變更（breakage），但僅提供高階描述而無最小化指令稿
• 重現依賴特定的訓練設定、分散式環境或複雜的基礎設施

1.6) 邊界情況與數值精確度

如果 issue 涉及極值或數值精確度差異：

需偵測的模式：

• 數值接近 torch.finfo(dtype).max 或 torch.finfo(dtype).min
• 合法（但極端）的輸入導致輸出出現 NaN/Inf
• CPU 與 GPU 執行結果存在差異
• 不同資料型態間的精確度差異（例如 fp32 vs fp16）
• 由 Fuzzer（模糊測試）產生的邊界情況

重要 — 避免被關鍵字誤導而標錯標籤：

請根據根本原因（root cause）標註標籤，而不是根據錯誤訊息或標題中出現的關鍵字。關鍵字只告訴你什麼地方失敗了，而不是為什麼失敗。

• 在 import torch 時出現 undefined symbol: ncclAlltoAll 錯誤屬於打包問題（module: binaries），而非分散式訓練的 bug — 使用者根本尚未執行分散式程式碼。
• 參數名稱或公差檢查（tolerance check）中出現 nan，除非 bug 確實與 NaN 傳播有關，否則不屬於 module: NaNs and Infs。
• Stack trace 中提及 autograd 並不意味著是 module: autograd — 請確認 bug 是在 autograd 本身還是僅在呼叫路徑上。
• 帶有公差門檻的測試失敗屬於 module: tests，而非 module: numerical-stability。

請思考：「修復程式碼需要落在哪裡？」這決定了應該標註什麼標籤。

處置方式：

1. 新增 module: edge cases 標籤
2. 若來自 fuzzer，一併新增 topic: fuzzer
3. 使用 templates.json 中的 numerical_accuracy 範本連結至官方說明文件
4. 若根據文件說明該 issue 明顯屬於預期行為，請搭配範本留言直接關閉 issue

2) 移轉 Issue（領域函式庫或 ExecuTorch）

若 issue 應歸屬於其他儲存庫（vision/text/audio/RL/ExecuTorch 等），請將 issue 移轉（transfer）並停止操作。

2.5) PT2 Issue — 特殊處理

PT2 不屬於重定向標籤。 oncall: pt2 與步驟 3 中的其他 oncall 標籤不同。PT2 issue 需繼續進行步驟 4 至 7 的完整分流流程 — 先新增 oncall: pt2，然後繼續標註 module: 標籤、標記 triaged 等。

每個 oncall: pt2 的 issue 都必須至少包含一個 module: 標籤。 若缺乏模組標籤，PT2 的值班佇列範圍會過於寬泛 — 團隊需要知道受影響的是哪一個組件（例如 module: dynamo、module: inductor、module: helion、module: dynamic shapes）。若無法確定具體模組，請使用 module: compile ux 作為後備選項，但請務必優先嘗試標註具體模組。詳細指引請參閱 pt2-triage-rubric.md。

3) 重定向至次要值班團隊（Secondary Oncall）

關鍵規則： 當將 issue 重定向至非 PT2 的值班佇列時，請標註恰好一個 oncall: ... 標籤並停止操作。切勿：

• 新增任何 module: 標籤
• 標記為 triaged
• 進行任何進一步的分流工作

子值班團隊會負責處理他們自己的分流。你的任務僅是將 issue 路由給他們。

值班重定向標籤（Oncall Redirect Labels）

標籤	使用時機
oncall: jit	TorchScript 相關 issue
oncall: distributed	分散式訓練（DDP、FSDP、RPC、c10d、DTensor、DeviceMesh、對稱記憶體、上下文平行、流水線平行）。特殊處理： 標註此標籤後，請對該 issue 呼叫分散式分流子 Skill（/distributed-triage）進行二級分流 — 它會路由至子值班團隊、新增模組標籤並標記已分流。
oncall: export	torch.export 相關 issue
oncall: quantization	量化（Quantization）相關 issue
oncall: mobile	行動端（iOS/Android），不包含 ExecuTorch
oncall: profiler	Profiler 相關 issue（CPU、GPU、Kineto）
oncall: visualization	TensorBoard 整合相關

應避免的常見路由錯誤：

• MPS ≠ Mobile。 MPS（Metal Performance Shaders）是 macOS/Apple Silicon 的 GPU 後端。請勿將 MPS issue 路由至 oncall: mobile。MPS issue 應留在通用佇列並標註 module: mps。
• DTensor → oncall: distributed。 即使未提及 DDP/FSDP，DTensor 的 issue 仍應一律路由至 oncall: distributed。
• ONNX → module: onnx。 沒有 oncall: onnx 標籤。請使用 module: onnx 並留在通用佇列。
• CI/releng → module: ci。 請勿使用 oncall: releng。CI 基礎設施 issue 請使用 module: ci。
• torch.compile + 分散式。 當 torch.compile 處理分散式算子（如 dist.all_reduce）出現問題時，issue 通常需要同時標註 oncall: pt2 與 oncall: distributed，因為修復可能跨越這兩個程式碼庫。

附註： oncall: cpu inductor 是 PT2 的子佇列。一般分流時，只需使用 oncall: pt2 即可。

4) 標註 Issue 標籤（若未移轉／重定向）

僅當 issue 留在通用佇列時：

• 根據受影響的領域新增 1 個以上的 module: ... 標籤
• 當具體標籤與通用標籤同時存在時，優先選擇具體標籤。請參考 labels.json 中的描述說明，以了解具體標籤何時取代通用標籤（例如 SDPA issue 使用 module: sdpa 而非 module: nn；flex attention 使用 module: flex attention 而非 module: nn）。
• feature — 目前以任何形式均不存在的全全新功能
• enhancement — 對現有已正常運作功能的改進（例如：為原本透過 fallback/composite 運行的算子新增原生後端 kernel、效能最佳化、更佳的錯誤訊息）。若改進與效能相關，需一併新增 module: performance。
• function request — 新函式或現有函式的新參數／模式
• 如果 issue 提到該操作「目前可運作」或「降級回退（falls back to）」較慢的路徑，這屬於 enhancement 而非 feature

常被遺漏的標籤 — 請務必檢查以下項目：

條件	標籤
段錯誤（Segfault）、非法記憶體存取、SIGSEGV	module: crash
效能問題：效能衰退（regression）、變慢或最佳化需求	module: performance
Windows 上的問題	module: windows
此前正常運作的功能現已損壞	module: regression
之前正常但現已損壞的文件／連結	module: docs + module: regression（而非 enhancement）
關於測試失敗的問題（而非底層功能本身）	module: tests
反向傳播／梯度計算 bug	module: autograd（除算子本身的模組標籤外額外新增）
torch.linalg 算子或線性代數算子（solve, svd, eig, inv 等）	module: linear algebra
has workaround	僅在替代方案非顯而易見且具備一定複雜度時才新增。若 issue 是「X 在不連續（non-contiguous）張量上無法運作」，呼叫 .contiguous() 只是 bug 的同義反轉，並不算替代方案