Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 32 additions & 20 deletions skills/rocm-doctor/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Step 0 (CLI install) runs before the step 1 examine check this points at. Consider noting the ordering here, or the deferral.

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,
Expand All @@ -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:
Expand Down Expand Up @@ -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`

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After asking which GPU, say what happens on each answer: NVIDIA/Intel/Apple declines per the gate, and AMD (e.g. the GPU is hidden by the very failure being diagnosed) should continue to rocm diagnose. As written the flow stops with no exit.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 43f1c74. After the question, step 1 now says what each answer does: AMD (or "cannot say") continues with rocm diagnose, and NVIDIA, Intel or Apple is declined by the scope gate. The text names a container without GPU passthrough and the failure itself as ways the GPU can be hidden.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: this examine branch is not graded by any eval (the recorded CLI refuses examine), so the regression it fixes can come back unnoticed. Worth a follow-up to teach evals/hooks.py examine --json.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, and not in this PR: the replay stub refuses examine, so grading it means teaching evals/hooks.py to answer examine --json from recordings and adding four evals (no-amd-gpu, wsl with has_amd_gpu false, ok, and examine failing). That is being filed as a follow-up ticket and I will link it here. Until then the branch is covered by scripted scenarios and local skillscope runs, as the description says.

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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Any other result: go on" also covers degraded, which can hide the GPU the same way a container without passthrough does (and the deferred unsupported-os). Consider naming degraded here.

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 "<paste the exact error>" --json
Expand Down Expand Up @@ -228,19 +238,21 @@ 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
<id>` 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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: fix-2-unset-override is print-only on WSL as well as Linux (PRINT_ON_LINUX_AND_WSL_AUTO_ON_WINDOWS in crates/rocm-core/src/fix/catalog.rs: "WSL runs that same Linux arm"), so auto_applicable is false there too. "on Linux" alone could read as true on WSL. Suggest "on Linux and WSL2" or "anywhere but Windows".

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 43f1c74. The auto_applicable sentence now says "on Linux and WSL2", and so does the fix-2 bullet in step 3 (WSL2 runs the same Linux arm).

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The catalog marks fix-2-unset-override print-only on WSL as well as Linux (print-only on linux/wsl, auto on windows), so auto_applicable is false there too. Say "on Linux and WSL".

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 43f1c74: "on Linux and WSL2", in the auto_applicable sentence and in the step 3 fix-2 bullet.

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
no reliable fix, and exits 0 having changed nothing.

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
Expand Down Expand Up @@ -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.
8 changes: 4 additions & 4 deletions skills/rocm-doctor/skill-card.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading