triaging-issues

The full skill.

Original instructions from the publisher’s SKILL.md

# PyTorch Issue Triage Skill

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

## Contents
- [MCP Tools Available](#mcp-tools-available)
- [Labels You Must NEVER Add](#labels-you-must-never-add)
- [Issue Triage Steps](#issue-triage-for-each-issue)
  - 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](#v1-constraints)

**Labels reference:** See [labels.json](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](pt2-triage-rubric.md) for detailed labeling guidance when triaging PT2/torch.compile issues.

**Response templates:** See [templates.json](templates.json) for standard response messages.

---

## MCP Tools Available

Use these GitHub MCP tools for triage:

| Tool | Purpose |
|------|---------|
| `mcp__github__get_issue` | Get issue details and existing labels |
| `mcp__github__get_issue_comments` | Get existing issue comments |
| `mcp__github__update_issue` | Apply labels or close issues |
| `mcp__github__add_issue_comment` | Add comment (only for redirecting questions) |
| `mcp__github__search_issues` | Find similar issues for context |

---

## Labels You Must NEVER Add

| Prefix/Category | Reason |
|-----------------|--------|
| Labels not in `labels.json` | Only apply labels that exist in the allowlist |
| `ciflow/*` | CI job triggers for PRs only |
| `test-config/*` | Test suite selectors for PRs only |
| `release notes: *` | Auto-assigned for release notes |
| `ci-*`, `ci:*` | CI infrastructure controls |
| `sev*` | Severity labels require human decision |
| `merge blocking` | Requires human decision |
| `actionable`, `needs design`, `needs reproduction`, `needs research` | Reserved for human reviewers after they have reviewed the issue |
| Any label containing "deprecated" | Obsolete |
| `oncall: releng` | Not a triage redirect target. Use `module: ci` instead |

**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](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

| Label | When to use |
|-------|-------------|
| `oncall: jit` | TorchScript issues |
| `oncall: distributed` | Distributed training (DDP, FSDP, RPC, c10d, DTensor, DeviceMesh, symmetric memory, context parallel, pipelining). **Special handling:** after applying this label, invoke the distributed triage sub-skill (`/distributed-triage` on this issue) for second-level triage — it will route to a sub-oncall, add module labels, and mark triaged. |
| `oncall: export` | torch.export issues |
| `oncall: quantization` | Quantization issues |
| `oncall: mobile` | Mobile (iOS/Android), excludes ExecuTorch |
| `oncall: profiler` | Profiler issues (CPU, GPU, Kineto) |
| `oncall: visualization` | TensorBoard integration |

**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:**

| Condition | Label |
|-----------|-------|
| Segfault, illegal memory access, SIGSEGV | `module: crash` |
| Performance issue: regression, slowdown, or optimization request | `module: performance` |
| Issue on Windows | `module: windows` |
| Previously working feature now broken | `module: regression` |
| Broken docs/links that previously worked | `module: docs` + `module: regression` (NOT `enhancement`) |
| Issue about a test failing (not the underlying functionality) | `module: tests` |
| Backward pass / gradient computation bug | `module: autograd` (in addition to the op's module label) |
| `torch.linalg` ops or linear algebra ops (solve, svd, eig, inv, etc.) | `module: linear algebra` |
| `has workaround` | Only add when the workaround is **non-trivial and non-obvious**. If the issue is "X doesn't work for non-contiguous tensors," calling `.contiguous()` is the tautological inverse of the bug, not a workaround. A real workaround is something like installing a specific package version, adding a synchronization point, inserting `gc.collect()`, or using a different API that isn't obviously implied by the bug description. |

**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 — Confirmed on the Latest Release

`release triage` is a narrow flag, not a catch-all. It 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`, do not add `release triage` at all.**

Add it only when **one of these two gates** is satisfied:

**Gate 1 — confirmed on the most recent released minor.** The issue states a PyTorch
version, and that version is the minor named in `RELEASE CONTEXT`, or one of its patch
releases. "States a version" means the version is written in the issue: the
`torch.__version__` line of the environment dump, a `pip install` line, or the reporter
saying so in prose. Read it out of the issue; never infer it from the traceback, the
issue date, or what you assume is current.

**Gate 2 — already labelled `high priority`.** The label is on the issue when you read
it, applied by a human in an earlier pass. This is the existing label only — it is not
your own 5a judgement. If *you* think an issue is high priority, 5a has you add
`triage review` and stop; that alone does not earn `release triage`.

Do **not** add it for any of the following on its own:

| Situation | Why not |
|---|---|
| Reproduces only on main, a nightly, or an RC | Not confirmed on a release. If it is serious, `triage review` in 5a is the path. |
| No version stated anywhere in the issue | Unconfirmed. Do not guess. |
| Stated version is older than the minor in `RELEASE CONTEXT` | Already shipped; not this train. |
| Crash, silent correctness, BC break, packaging or install bug | Severity is not a gate. It qualifies only if it also clears gate 1 or gate 2. |
| It looks like it *would* ship broken | Speculative. |
| Feature request, enhancement, or documentation-only | Never `release triage`, under either gate. |

**When unsure, leave it off.** This label is read as a short list that the release
manager works through by hand, so a false positive costs more than a miss: a list that
fills with maybes stops being read, and then it catches nothing. Anything genuinely
urgent still reaches a human through `triage review` in 5a.

`release triage` is independent of the 5a decision — an issue can carry both — and it
remains a flag, not a verdict: whether to cherry-pick is never the bot's call.

### 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` only when the issue is confirmed on the most recent released minor, or already carries `high priority` (step 5b); when unsure, leave it off
- 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.