Agent skill · research science · pytorch
pt2-bug-basher
Debug PyTorch 2 compiler stack failures including Dynamo graph breaks, Inductor codegen errors, AOTAutograd crashes, and accuracy mismatches. Use when encountering torch.compile errors, BackendCompilerFailed exceptions, recompilation issues, Triton kernel failures, FX graph problems, or when the user mentions debugging PT2, Dynamo, Inductor, or compiled model issues.
Why this skill is useful
Adds a detailed, executable debugging workflow for PyTorch 2 compiler stack failures that includes environment checks, test creation, and validation steps.
What it needs
Requires pytest installed locally. About 7k tokens when loaded. Last updated 2026-08-07. 102,253 stars on the source repository.
What this skill does
PT2 Bug Basher Debug test failures and runtime errors in the PyTorch 2 compiler stack (Dynamo, Inductor, AOTAutograd, FX graphs). Workflow Summary 1. Environment check -- Ask the user which conda environment to use. Verify it is active by checking $CONDADEFAULTENV. Then run python -c "import torch; print(torch.version)" to confirm torch is importable and report the version. If the environment is not active or torch cannot be imported, stop and ask the user to activate the correct environment before proceeding. 2. Reproduce -- Get a consistent reproduction of the failure 3. Minimize -- Reduce the repro to the smallest possible standalone case. Strip away unrelated model logic, use minimal tensor shapes, and isolate the specific op or pattern that triggers the bug. 4. Add a unit test -- Do this BEFORE diving into code search or root cause investigation. Add a failing test to the codebase that captures the bug. Place it in a specific, topic-appropriate test file (e.g., test/dynamo/testrepros.py, test/inductor/testtorchinductor.py, test/export/testexport.py). Avoid test/dynamo/testmisc.py — it is already oversized; find a more specific test file that matches the area of the bug. Use torch.testing.internal.commonutils.TestCase and runtests. The test must fail before the fix and pass after. Having the test first keeps you grounded — you know exactly what "fixed" looks like before you start exploring the codebase. 5. Validate on main -- Use EnterWorktree to create a worktree checked out at main. Copy the new test file into the worktree and run the test there to confirm it fails on main. If the test passes on main, stop — the test may not be capturing the right bug, or the bug may already be fixed. Exit the worktree with ExitWorktree (action: remove) and return to the working branch before continuing. 6. Gather logs -- Run with appropriate TORCHLOGS settings 7. Classify -- Use the Error Triage table to identify the category 8. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills pytorch/pt2-bug-basher