|
| 1 | +--- |
| 2 | +name: rocm-doctor |
| 3 | +description: >- |
| 4 | + Diagnoses why ROCm, the HIP SDK, PyTorch, or llama.cpp is broken on an AMD GPU |
| 5 | + on Linux or Windows, then applies a low-risk fix with consent or hands back the |
| 6 | + exact next step. Also routes Lemonade, LM Studio, and Ollama problems to the |
| 7 | + right upstream channel. Use when the user reports that ROCm or HIP "isn't |
| 8 | + working", torch.cuda.is_available() is False, rocminfo / hipInfo can't see the |
| 9 | + GPU, or hits hipErrorNoBinaryForGpu, HSA_STATUS_ERROR_INVALID_ISA, "invalid |
| 10 | + device function", "no kernel image is available", cannot open /dev/kfd, |
| 11 | + permission denied on /dev/kfd, "ROCk module is NOT loaded", a missing |
| 12 | + libamdhip64.so / amdhip64_6.dll / hipblas.dll / vcruntime140_1.dll, an |
| 13 | + HSA_OVERRIDE_GFX_VERSION page fault, an iGPU+dGPU crash, a container that can't |
| 14 | + see the GPU, or an amdgpu-install / DKMS failure. Backed by the `rocm` CLI |
| 15 | + (`rocm examine` / `rocm diagnose` / `rocm fix`); this skill is a thin driver |
| 16 | + over those commands, not a re-implementation. |
| 17 | +--- |
| 18 | + |
| 19 | +# ROCm Doctor |
| 20 | + |
| 21 | +Given a "ROCm / PyTorch / llama.cpp isn't working on my AMD GPU" complaint, |
| 22 | +identify which **known misconfiguration** is the cause and either fix it (with |
| 23 | +consent) or hand back the exact next step. |
| 24 | + |
| 25 | +This skill does **not** probe or reason on its own. The `rocm` CLI owns the |
| 26 | +probe, the closed failure-mode catalog, and the fixes; the skill just drives it |
| 27 | +and relays the results. The catalog is a **closed list** — if the symptom |
| 28 | +doesn't match a known mode, route the user upstream instead of guessing. |
| 29 | + |
| 30 | +## Workflow |
| 31 | + |
| 32 | +0. **Ensure the `rocm` CLI is present.** Everything below shells out to it, so |
| 33 | + check first and install it if missing: |
| 34 | + |
| 35 | + ``` |
| 36 | + rocm --version |
| 37 | + ``` |
| 38 | + |
| 39 | + If that succeeds, skip to step 1. If it's not found, install it **with the |
| 40 | + user's consent** (this fetches and runs an installer that drops the `rocm` and |
| 41 | + `rocmd` binaries into `~/.local/bin`). Only nightly builds are published |
| 42 | + today, so install from the `nightly` channel: |
| 43 | + |
| 44 | + - **Linux / macOS:** |
| 45 | + ``` |
| 46 | + curl -fsSL https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.sh | sh -s -- nightly |
| 47 | + ``` |
| 48 | + - **Windows (PowerShell):** |
| 49 | + ``` |
| 50 | + $env:ROCM_CLI_CHANNEL = "nightly" |
| 51 | + irm https://raw.githubusercontent.com/ROCm/rocm-cli/main/install.ps1 | iex |
| 52 | + ``` |
| 53 | +
|
| 54 | + (Once rocm-cli cuts a stable release, drop the `nightly` channel — `sh` / |
| 55 | + `iex` alone will pull the latest stable build.) |
| 56 | +
|
| 57 | + After install, confirm `~/.local/bin` is on `PATH` and re-run `rocm --version`. |
| 58 | + If it still isn't available, hand the user the install page |
| 59 | + (https://github.com/ROCm/rocm-cli) and stop. |
| 60 | +
|
| 61 | +1. **Diagnose.** Pass the user's error text as the symptom: |
| 62 | +
|
| 63 | + ``` |
| 64 | + rocm diagnose --symptom "<paste the exact error>" --json |
| 65 | + ``` |
| 66 | +
|
| 67 | + Read the JSON: |
| 68 | + - `matched[]` — ranked causes, each with `id`, `title`, `score` (0–100), |
| 69 | + `evidence[]`, and a `fix` (with `fix_id`, `summary`, `commands`, `verify`, |
| 70 | + `notes`, and the `needs_sudo` / `needs_reboot` / `needs_relogin` / |
| 71 | + `auto_applicable` flags). `score >= 75` = high confidence; `50–74` = likely |
| 72 | + (confirm one more piece of evidence with the user first). |
| 73 | + - `out_of_scope` — when set (e.g. WSL2), do **not** diagnose. First, if the |
| 74 | + user's symptom clearly names an app that ships its own runtime (Lemonade, |
| 75 | + Ollama, LM Studio), route them to that app's tracker (see |
| 76 | + [Framework routing](#framework-routing)) — those trackers apply regardless |
| 77 | + of platform. Otherwise relay the `out_of_scope` message and stop (see |
| 78 | + [Out of scope](#out-of-scope)). |
| 79 | + - `route_when_no_match` — when `matched` is empty, hand the user this |
| 80 | + upstream tracker; **do not speculate**. Note the CLI picks this target from |
| 81 | + the *host-detected* framework, not from the symptom text — so for an app |
| 82 | + named only in the symptom, route it yourself per |
| 83 | + [Framework routing](#framework-routing). |
| 84 | +
|
| 85 | +2. **Propose the fix.** Show the top match's `title`, `evidence`, plan, and |
| 86 | + `verify` command. Only propose applying it when the user is on board. |
| 87 | +
|
| 88 | +3. **Apply with consent.** For an auto-applicable fix: |
| 89 | +
|
| 90 | + ``` |
| 91 | + rocm fix <fix-id> # auto fixes: prompt before changing anything |
| 92 | + rocm fix <fix-id> --dry-run # show the exact change, touch nothing |
| 93 | + rocm fix <fix-id> --yes # required to apply in a non-interactive shell |
| 94 | + ``` |
| 95 | +
|
| 96 | + Only the four auto-applicable fixes prompt and mutate. The other 11 are |
| 97 | + **print-only** (bootloader, kernel, reinstall, Windows driver, …): `rocm fix |
| 98 | + <id>` just prints the plan for the user to run themselves — no prompt, and the |
| 99 | + CLI never performs those. |
| 100 | +
|
| 101 | +4. **Verify.** Have the user run the `verify` command from the diagnosis. |
| 102 | +
|
| 103 | +Use `rocm examine` (or `rocm examine --json`) when you only need the host state |
| 104 | +(GPU, driver, ROCm install, groups, framework) without a diagnosis. |
| 105 | +
|
| 106 | +## Framework routing |
| 107 | +
|
| 108 | +`rocm diagnose` covers frameworks that build against the **system** ROCm/HIP: |
| 109 | +
|
| 110 | +- **PyTorch**, **llama.cpp** — in scope; diagnose normally. |
| 111 | +
|
| 112 | +Apps that ship their **own** ROCm runtime aren't diagnosed here — route the user |
| 113 | +to the right tracker. (The CLI's `route_when_no_match` also targets these, but |
| 114 | +only when the host probe *detects* that app; when the app is named only in the |
| 115 | +symptom, do the routing yourself using the list below.) |
| 116 | +
|
| 117 | +- **Lemonade** → https://github.com/lemonade-sdk/lemonade/issues |
| 118 | +- **Ollama** → https://github.com/ollama/ollama/issues |
| 119 | +- **LM Studio** → in-app support (no public repo) |
| 120 | +- Anything else with no catalog match → ROCm core: |
| 121 | + https://github.com/ROCm/ROCm/issues (this is what `route_when_no_match` |
| 122 | + returns by default). |
| 123 | +
|
| 124 | +## Out of scope |
| 125 | +
|
| 126 | +- **WSL2** — a distinct platform (`/dev/dxg` + the Windows host driver, not the |
| 127 | + in-tree `amdgpu` module or `/dev/kfd`). `rocm examine`/`diagnose` detect it and |
| 128 | + route out; relay that guidance and point at AMD's ROCm-on-WSL guide. |
| 129 | +- **NVIDIA / Intel / Apple Silicon GPUs**, and **fresh installs on a clean |
| 130 | + machine** (a setup task, not a diagnosis). Exit cleanly and say so. |
| 131 | +
|
| 132 | +## Rules |
| 133 | +
|
| 134 | +- Never invent a fix. If `rocm diagnose` returns no match, route upstream. |
| 135 | +- Never run a mutating fix without the user's explicit OK; prefer `--dry-run` |
| 136 | + first. New failure modes are added to the CLI catalog, not improvised here. |
| 137 | +
|
| 138 | +See `reference.md` for the full closed catalog and the CLI command/exit-code |
| 139 | +reference. |
0 commit comments