Triaging Issues

PyTorch Issue Triage Skill

This skill helps triage GitHub issues by routing issues, applying labels, and leaving first-line responses.

Contents

• MCP Tools Available
• Labels You Must NEVER Add
• Issue Triage Steps
  • Step 0: Already Routed — SKIP
  • Step 1: Question vs Bug/Feature
  • Step 1.5: Needs Reproduction — External Files
  • Step 2: Transfer
  • Step 2.5: PT2 Issues — Special Handling
  • Step 3: Redirect to Secondary Oncall
  • Step 4: Label the Issue
  • Step 5: Escalate — High Priority (human review), then release triage
  • Step 6: bot-triaged (automatic)
  • Step 7: Mark Triaged
• V1 Constraints

Labels reference: See labels.json for the full catalog of labels suitable for triage. ONLY apply labels that exist in this file. Do not invent or guess label names. This file excludes CI triggers, test configs, release notes, deprecated labels, and labels requiring human decision.

PT2 triage guide: See pt2-triage-rubric.md for detailed labeling guidance when triaging PT2/torch.compile issues.

Response templates: See templates.json for standard response messages.

MCP Tools Available

Use these GitHub MCP tools for triage:

Labels You Must NEVER Add

If blocked: When a label is blocked by the hook, add ONLY triage review and stop. A human will handle it.

These rules are enforced by a PreToolUse hook that validates all labels against labels.json.

Never Override Human Labels

If a human has already applied labels (especially ci: sev, severity labels, or priority labels), do NOT remove or replace them. Your job is to supplement, not override.

Issue Triage (for each issue)

0) Already Routed — SKIP

If an issue already has ANY oncall: label, SKIP IT entirely. Do not:

• Add any labels
• Add triaged
• Leave comments
• Do any triage work

That issue belongs to the sub-oncall team. They own their queue.

1) Question vs Bug/Feature

• If it is a question (not a bug report or feature request): close and use the redirect_to_forum template from templates.json.
• If unclear whether it is a bug/feature vs a question: request additional information using the request_more_info template and stop.

1.5) External Files

Check if the issue body contains links to external files that users would need to download to reproduce.

Patterns to detect:

• File attachments: .zip, .pt, .pth, .pkl, .safetensors, .onnx, .bin files
• External storage: Google Drive, Dropbox, OneDrive, Mega, WeTransfer links
• Model hubs: Hugging Face Hub links to model files

Action:

1. Edit the issue body to remove/redact the download links
   • Replace with: [Link removed - external file downloads are not permitted for security reasons]
2. Use the request_self_contained_reproduction template from templates.json
3. Do NOT add triaged — wait for the user to provide a reproducible example

1.55) Missing Reproduction — Other Cases

Request a self-contained reproduction and stop when:

• The user reports a hardware-specific issue (e.g., specific GPU model) without a self-contained repro script
• The user references a specific model/checkpoint/dataset that is not publicly runnable in a few lines
• The issue describes version-upgrade breakage but only provides a high-level description without a minimal script
• The repro depends on a specific training setup, distributed environment, or non-trivial infrastructure

1.6) Edge Cases & Numerical Accuracy

If the issue involves extremal values or numerical precision differences:

Patterns to detect:

• Values near torch.finfo(dtype).max or torch.finfo(dtype).min
• NaN/Inf appearing in outputs from valid (but extreme) inputs
• Differences between CPU and GPU results
• Precision differences between dtypes (e.g., fp32 vs fp16)
• Fuzzer-generated edge cases

IMPORTANT — avoid keyword-triggered mislabeling:

Label based on the root cause, not keywords that appear in the error or title. A keyword tells you what failed, not why.

• An undefined symbol: ncclAlltoAll error at import torch is a packaging issue (module: binaries), not a distributed training bug — the user never ran distributed code.
• A nan in a parameter name or tolerance check is not module: NaNs and Infs unless the bug is actually about NaN propagation.
• A stack trace mentioning autograd does not mean module: autograd — check whether the bug is in autograd itself or just on the call path.
• A test failure with tolerance thresholds is module: tests, not module: numerical-stability.

Ask: "Where would the fix need to be made?" That determines the label.

Action:

1. Add module: edge cases label
2. If from a fuzzer, also add topic: fuzzer
3. Use the numerical_accuracy template from templates.json to link to the docs
4. If the issue is clearly expected behavior per the docs, close it with the template comment

2) Transfer (domain library or ExecuTorch)

If the issue belongs in another repo (vision/text/audio/RL/ExecuTorch/etc.), transfer the issue and STOP.

2.5) PT2 Issues — Special Handling

PT2 is NOT a redirect. oncall: pt2 is not like the other oncall labels in Step 3. PT2 issues continue through Steps 4–7 for full triage — add oncall: pt2, then proceed to label with module: labels, mark triaged, etc.

Every oncall: pt2 issue MUST have at least one module: label. The PT2 oncall queue is too broad without a module label — the team needs to know which component is affected (e.g., module: dynamo, module: inductor, module: helion, module: dynamic shapes). If you cannot determine the specific module, use module: compile ux as a fallback, but always try to be specific first. See pt2-triage-rubric.md for detailed guidance.

3) Redirect to Secondary Oncall

CRITICAL: When redirecting issues to a non-PT2 oncall queue, apply exactly one oncall: ... label and STOP. Do NOT:

• Add any module: labels
• Mark it triaged
• Do any further triage work

The sub-oncall team will handle their own triage. Your job is only to route it to them.

Oncall Redirect Labels

Common routing mistakes to avoid:

• MPS ≠ Mobile. MPS (Metal Performance Shaders) is the macOS/Apple Silicon GPU backend. Do NOT route MPS issues to oncall: mobile. MPS issues stay in the general queue with module: mps.
• DTensor → oncall: distributed. DTensor issues should always be routed to oncall: distributed, even if they don't mention DDP/FSDP.
• ONNX → module: onnx. There is no oncall: onnx. Use module: onnx and keep in the general queue.
• CI/releng → module: ci. Do not use oncall: releng. Use module: ci for CI infrastructure issues.
• torch.compile + distributed. When torch.compile mishandles a distributed op (e.g., dist.all_reduce), the issue typically needs BOTH oncall: pt2 and oncall: distributed since the fix may span both codebases.

Note: oncall: cpu inductor is a sub-queue of PT2. For general triage, just use oncall: pt2.

4) Label the issue (if NOT transferred/redirected)

Only if the issue stays in the general queue:

• Add 1+ module: ... labels based on the affected area
• Prefer specific labels over general ones when both exist. Check labels.json descriptions for guidance on when a specific label supersedes a general one (e.g., module: sdpa instead of module: nn for SDPA issues, module: flex attention instead of module: nn for flex attention).
• feature — wholly new functionality that does not exist today in any form
• enhancement — improvement to something that already works (e.g., adding a native backend kernel for an op that already runs via fallback/composite, performance optimization, better error messages). If the enhancement is about performance, also add module: performance.
• function request — a new function or new arguments/modes for an existing function
• If the issue says the operation "currently works" or "falls back to" a slower path, that is enhancement, not feature

Commonly missed labels — always check for these:

Label based on the actual bug, not keywords. Read the issue to understand what is actually broken. A bug about broadcasting that happens to mention "nan" in a parameter name is a frontend bug, not a NaN/Inf bug.

5) Escalate — High Priority (human review), then release triage

Two independent decisions, in this order. Work through 5a first, then 5b for every issue — 5b is not limited to issues you escalated in 5a, and an issue can end up with both labels, one, or neither.

5a) High Priority — REQUIRES HUMAN REVIEW

CRITICAL: If you believe an issue is high priority, you MUST:

1. Add triage review label and do not add triaged

Do NOT directly add high priority without human confirmation.

High priority criteria:

• Crash / segfault / illegal memory access
• Silent correctness issue (wrong results without error)
• Regression from a prior version
• Internal assert failure
• Many users affected
• Core component or popular model impact

5b) release triage — Affects an Upcoming Release

Add release triage when an issue would affect a release if it went unfixed. The label only surfaces the issue for whoever owns the release; it is not a cherry-pick request and does not decide anything.

You are told which version is current — never guess it. Your prompt carries a RELEASE CONTEXT block giving the most recent released minor version. If the block says unknown, skip the two version-dependent criteria below and judge the rest on their own merits.

Add it when any of these hold:

• Regression against the most recent released minor version. The issue reports something that worked on that minor (or later) and is broken now. Pair it with module: regression. If the last-working version is older than that minor, it is not release-relevant.
• Critical correctness or stability: silent correctness (wrong results, no error), backwards-compatibility break, crash / segfault, deadlock or hang, or a large memory leak.
• Critical fix to a feature introduced in the most recent minor release — new surface that shipped broken. Go by what the issue says ("new in 2.x", "added in 2.x", "since upgrading to 2.x") checked against the version in RELEASE CONTEXT; do not try to recall which features shipped in which release.
• Binary / packaging: anything affecting wheels, Docker images, install, or the release build itself. Pair it with module: binaries.
• Would ship broken in the next release. A defect on main, a nightly, an RC, or the release branch that reaches users if nobody fixes it — including anything surfaced by release validation or downstream canaries. This holds even when it is not a regression against anything, e.g. a bug in code that has never shipped.

Apply it generously. A false positive costs the release manager one glance; a miss costs a broken release. When unsure, add it.

release triage is independent of the triage review decision in 5a — an issue can carry both. Do not add it to feature requests, enhancements, or documentation-only issues, and do not add it for a regression against a version older than the last released minor.

6) bot-triaged (automatic)

The bot-triaged label is automatically applied by a post-hook after any issue mutation. You do not need to add it manually.

7) Mark triaged

If not transferred/redirected and not flagged for review, add triaged.

V1 Constraints

DO NOT:

• Close bug reports or feature requests automatically
• Close issues unless they are clear usage questions per Step 1
• Assign issues to users
• Add high priority directly without human confirmation
• Add module labels when redirecting to oncall
• Add comments to bug reports or feature requests, except a single info request when classification is unclear

DO:

• Close clear usage questions and point to discuss.pytorch.org (per step 1)
• Be conservative - when in doubt, add triage review for human attention
• Add release triage whenever an issue would affect an upcoming release (step 5b); err toward adding it
• Apply type labels (feature, enhancement, function request) when confident
• Add triaged label when classification is complete

Note: bot-triaged is automatically applied by a post-hook after any issue mutation.