Rocm Doctor

ROCm Doctor

Given a "ROCm / PyTorch / llama.cpp isn't working on my AMD GPU" complaint, identify which known misconfiguration is the cause and either fix it (with consent) or hand back the exact next step.

This skill does not probe or reason on its own. The rocm CLI owns the probe, the closed failure-mode catalog, and the fixes; the skill just drives it and relays the results. The catalog is a closed list — if the symptom doesn't match a known mode, route the user upstream instead of guessing.

Scope gate — check before anything else

Read the user's symptom and answer one question first: is this an AMD GPU on native Linux or Windows?

If it is not — an NVIDIA / Intel / Apple GPU, or anything running under WSL2 — then stop and decline:

• Say plainly that it is out of scope for this skill and why (not an AMD GPU / WSL2 is a separate platform).
• Give no troubleshooting for it: no commands to run, no driver or CUDA advice, no diagnostic checklist, no "try this first" — not even generic GPU suggestions. Point at the vendor's own docs (or AMD's ROCm-on-WSL guide) and stop there.
• Do not run rocm examine / rocm diagnose / rocm fix.

Being helpful here means being honest about the boundary — confidently-wrong advice for a stack this skill does not cover is worse than no advice. Only continue past this gate when the GPU is AMD and the platform is native Linux or Windows. See Out of scope.

Prerequisites

• The rocm CLI. This skill is only a driver over it; Phase 0 below installs it with the user's consent if rocm --version fails. Nothing else here is assumed — the CLI does the probing.
• Platform: native Linux (in-tree amdgpu module + /dev/kfd) or Windows (HIP SDK). WSL2, NVIDIA/Intel/Apple GPUs, and clean-machine installs are out of scope (see Out of scope).
• No fixed ROCm version, GPU arch (gfx…), or container image is assumed — rocm examine/diagnose detect the installed ROCm, the GPU's gfx target, and container context, and match fixes to what they find. Never hand-set HSA_OVERRIDE_GFX_VERSION (or similar footgun env vars) yourself; let the CLI decide.

Workflow

Only start here once the Scope gate passes — the GPU is AMD and the platform is native Linux or Windows.

0. Ensure the rocm CLI is present. Everything below shells out to it, so check first and install it if missing:

   rocm --version
   

   If that succeeds, skip to step 1. If it's not found, install it with the user's consent (this fetches and runs an installer that drops the rocm and rocmd binaries into ~/.local/bin). Only nightly builds are published today, so install from the nightly channel:

   • Linux / macOS:

     curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh -s -- nightly
     

   • Windows (PowerShell):

     $env:ROCM_CLI_CHANNEL = "nightly"
     irm https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.ps1 | iex
     

   (Once rocm-cli cuts a stable release, drop the nightly channel — sh / iex alone will pull the latest stable build.)

   After install, confirm ~/.local/bin is on PATH and re-run rocm --version. If it still isn't available, hand the user the install page (https://github.com/ROCm/rocm-cli) and stop.

1. Diagnose. Pass the user's error text as the symptom:

   rocm diagnose --symptom "<paste the exact error>" --json
   

   Read the JSON:

   • matched[] — ranked causes, each with id, title, score (0–100), evidence[], and a fix (with fix_id, summary, commands, verify, notes, and the needs_sudo / needs_reboot / needs_relogin / auto_applicable flags). score >= 75 = high confidence; 50–74 = likely (confirm one more piece of evidence with the user first).
   • out_of_scope — when set (e.g. WSL2), do not diagnose. First, if the user's symptom clearly names an app that ships its own runtime (Lemonade, Ollama, LM Studio), route them to that app's tracker (see Framework routing) — those trackers apply regardless of platform. Otherwise relay the out_of_scope message and stop (see Out of scope).
   • route_when_no_match — when matched is empty, hand the user this upstream tracker; do not speculate. Note the CLI picks this target from the host-detected framework, not from the symptom text — so for an app named only in the symptom, route it yourself per Framework routing.

2. Propose the fix. Show the top match's title, evidence, plan, and verify command. Only propose applying it when the user is on board.

3. Apply with consent. For an auto-applicable fix:

   rocm fix <fix-id>            # auto fixes: prompt before changing anything
   rocm fix <fix-id> --dry-run  # show the exact change, touch nothing
   rocm fix <fix-id> --yes      # required to apply in a non-interactive shell
   

   Only the four auto-applicable fixes prompt and mutate. The other 11 are print-only (bootloader, kernel, reinstall, Windows driver, …): rocm fix <id> just prints the plan for the user to run themselves — no prompt, and the CLI never performs those.

4. Verify. Have the user run the verify command from the diagnosis.

Use rocm examine (or rocm examine --json) when you only need the host state (GPU, driver, ROCm install, groups, framework) without a diagnosis.

Framework routing

rocm diagnose covers frameworks that build against the system ROCm/HIP:

• PyTorch, llama.cpp — in scope; diagnose normally.

Apps that ship their own ROCm runtime aren't diagnosed here — route the user to the right tracker. (The CLI's route_when_no_match also targets these, but only when the host probe detects that app; when the app is named only in the symptom, do the routing yourself using the list below.)

• Lemonade → https://github.com/lemonade-sdk/lemonade/issues
• Ollama → https://github.com/ollama/ollama/issues
• LM Studio → in-app support (no public repo)
• Anything else with no catalog match → ROCm core: https://github.com/ROCm/ROCm/issues (this is what route_when_no_match returns by default).

Out of scope

• WSL2 — a distinct platform (/dev/dxg + the Windows host driver, not the in-tree amdgpu module or /dev/kfd). rocm examine/diagnose detect it and route out; relay that guidance and point at AMD's ROCm-on-WSL guide.
• NVIDIA / Intel / Apple Silicon GPUs, and fresh installs on a clean machine (a setup task, not a diagnosis). Exit cleanly and say so.

Rules

• Never run the workflow — or offer any troubleshooting, generic GPU fixes included — for a non-AMD GPU or a WSL2 setup. State it is out of scope and stop.
• Never invent a fix. If rocm diagnose returns no match, route upstream.
• Never run a mutating fix without the user's explicit OK; prefer --dry-run first. New failure modes are added to the CLI catalog, not improvised here.

See reference.md for the full closed catalog and the CLI command/exit-code reference.