From a1a81ee806e2c807aa3259ef4c752b5ce9d5420e Mon Sep 17 00:00:00 2001 From: Eugene Volen Date: Fri, 6 Nov 2026 16:31:36 +0200 Subject: [PATCH] fix(skill): run examine for an unnamed vendor and finish the vocabulary Review of #909 found four things left over. The rule that asks which GPU the machine has when rocm examine reports no-amd-gpu had no step that ran examine, so a user who named no vendor on a host without an AMD GPU still got has_match false and an upstream route. Step 1 now runs rocm examine --json first when no vendor is named. The scope gate's closing line, "only continue when the GPU is AMD", could be read as overriding the unnamed-vendor rule, and nothing brought the decline back when the user then named another vendor. It now continues for an AMD or an unnamed vendor and declines for NVIDIA, Intel or Apple. "The auto-applicable set" was still in the contract-check paragraph, and step 1 showed the auto_applicable flag while step 3 said "has a runner". The paragraph now says which fixes have a runner, and step 3 says what the flag means: true only where the fix class is auto on this host. The closing pointer to reference.md lost "the full closed catalog", and the skill card's Description had become a run-on that dropped "print-only" for the two vLLM failures. Both are restored. Review then added three more. The Workflow intro still said the GPU is AMD, which stopped an unnamed vendor there too; it now says AMD or no vendor was named. After asking which GPU, the flow had no exit for an answer of AMD, or for a user who cannot say, such as a container without GPU passthrough. It now continues with rocm diagnose, which only reads. On WSL2 examine reports status wsl whatever the GPU, so step 1 reads has_amd_gpu there. fix-2 is print-only on WSL2 as well as Linux, so the notes say Linux and WSL2. A second review pass found two more. A failed rocm examine fell under "any other result: go on". examine exits 0 whenever it ran, so a non-zero exit is an error from the CLI; step 1 now relays the error and stops, as the contract check does. The scope gate's "treat ROCm / HIP wording as AMD and continue" read as in tension with step 1, which then asks which GPU. It now says to continue to step 1, which checks the host. Signed-off-by: Eugene Volen --- skills/rocm-doctor/SKILL.md | 52 ++++++++++++++++++++------------ skills/rocm-doctor/skill-card.md | 8 ++--- 2 files changed, 36 insertions(+), 24 deletions(-) diff --git a/skills/rocm-doctor/SKILL.md b/skills/rocm-doctor/SKILL.md index cffb776470..c3377ee89b 100644 --- a/skills/rocm-doctor/SKILL.md +++ b/skills/rocm-doctor/SKILL.md @@ -45,12 +45,10 @@ advice for a stack this skill does not cover is worse than no advice. A fresh install on a clean machine is out of scope too: that is a setup task, not a diagnosis. Exit cleanly and say so. -If the user names no GPU vendor, treat ROCm / HIP wording as AMD and continue. -Should `rocm examine` then report `no-amd-gpu`, the CLI found no AMD GPU: say so, -ask which GPU the machine has, and propose no fix until that is settled. That -status alone does not prove the GPU is not AMD. - -Only continue past this gate when the GPU is AMD. +If the user names no GPU vendor, treat ROCm / HIP wording as AMD and continue to +step 1, which checks what the machine has. Continue when the GPU is AMD or no +vendor is named. If the user then says it is NVIDIA, Intel or Apple, decline as +above. **WSL2 is in scope** and does not stop this gate. It is a platform family of its own, with its own catalog entries covering `/dev/dxg`, the DXCore handoff, @@ -76,7 +74,7 @@ offered there. ## Workflow Only start here once the [Scope gate](#scope-gate--check-before-anything-else) -passes — the GPU is AMD. +passes — the GPU is AMD or no vendor was named. 0. **Ensure the `rocm` CLI is present.** Everything below shells out to it, so check first and install it if missing: @@ -134,11 +132,23 @@ passes — the GPU is AMD. Any other failure, such as a different exit code or output with no `contract_version`, is an error from the CLI and not proof that it is old. Relay the error text and stop, because reinstalling the same version would not - clear it. Against a CLI without this contract, the entry ids, the - auto-applicable set, and the exit codes this skill documents are guesses, and a - guess presented as a fact is the failure this check prevents. - -1. **Diagnose.** Pass the user's error text as the symptom: + clear it. Against a CLI without this contract, the entry ids, which fixes have + a runner, and the exit codes this skill documents are guesses, and a guess + presented as a fact is the failure this check prevents. + +1. **Diagnose.** If the user named no GPU vendor, run `rocm examine --json` + first. Status `no-amd-gpu` means the CLI found no AMD GPU. On WSL2 the status + is `wsl` whatever the GPU, so read `has_amd_gpu` there: false means the same. + Either way, say so, ask which GPU the machine has, and propose no fix until + that is settled. That result alone does not prove the GPU is not AMD: a + container without GPU passthrough, or the very failure being diagnosed, can + hide it. If the user confirms AMD or cannot say, continue with `rocm diagnose` + below, which only reads; if the answer is NVIDIA, Intel or Apple, the scope + gate declines. Any other result: go on. If `rocm examine` itself fails (it + exits 0 whenever it ran, so a non-zero exit is an error from the CLI), relay + the error text and stop, as the contract check does. + + Pass the user's error text as the symptom: ``` rocm diagnose --symptom "" --json @@ -228,7 +238,9 @@ passes — the GPU is AMD. Only four fixes have a runner the CLI executes itself. The other 24 are **print-only** (bootloader, kernel, reinstall, Windows driver, …): `rocm fix ` just prints the plan for the user to run themselves — no prompt, and the - CLI never performs those. + CLI never performs those. In a diagnosis, `fix.auto_applicable` is true only + for a fix whose `fix.class` is auto on this host, so it is false for + `fix-9-igpu-dgpu` and for `fix-2-unset-override` on Linux and WSL2. One entry is in neither group. `info-20-gpu-no-rocm-support` is **diagnose-only**: `rocm fix` takes the id, names the problem, says there is @@ -236,11 +248,11 @@ passes — the GPU is AMD. Of the four, two do not always mutate: - - **`fix-2-unset-override` mutates on Windows only.** On Linux it reports - where the override is set and which rc files carry it, then stops — it - will not edit the user's dotfiles. So there is no prompt to answer and - nothing for `--dry-run` to preview. Tell the Linux user what to edit; do - not describe it as a change the CLI made or previewed. + - **`fix-2-unset-override` mutates on Windows only.** On Linux and WSL2 it + reports where the override is set and which rc files carry it, then stops + — it will not edit the user's dotfiles. So there is no prompt to answer and + nothing for `--dry-run` to preview. Tell the user what to edit; do not + describe it as a change the CLI made or previewed. - **`fix-9-igpu-dgpu` mutates only when `--device-index N` is passed.** Without it — on either platform — the runner just prints the `rocminfo`/`hipInfo` query that identifies the discrete GPU's index and @@ -308,5 +320,5 @@ start of the reply, before relaying a multi-step plan. first. New failure modes are added to the CLI catalog, not improvised here. Read [reference.md](reference.md) when `rocm fix` exits non-zero (its exit codes -are listed there), and before telling the user which platforms a fix id applies -to. +are listed there), before telling the user which platforms a fix id applies to, +and for the full closed catalog. diff --git a/skills/rocm-doctor/skill-card.md b/skills/rocm-doctor/skill-card.md index 96a01cdcaf..94e3dcf1d4 100644 --- a/skills/rocm-doctor/skill-card.md +++ b/skills/rocm-doctor/skill-card.md @@ -3,10 +3,10 @@ ## Description Diagnoses ROCm / HIP SDK / PyTorch / llama.cpp failures on AMD GPUs (Linux, -Windows, and WSL2) against a closed list of known misconfigurations, and applies a -low-risk fix with consent or routes the user to the right upstream channel, and -covers two vLLM startup failures (running out of GPU memory, an engine import -error) on Linux and WSL2. +Windows, and WSL2) against a closed list of known misconfigurations, including two +print-only vLLM startup failures on Linux and WSL2 (running out of GPU memory, an +engine import error), and applies a low-risk fix with consent or routes the user +to the right upstream channel. ## Owner