learn(skills/doctor-triage.md): triage a red doctor.sh before proposing a fix

[MendixMau]

Direct lane (changes to skills/, bug-logs/, bin/, project-bin/, project-tests/, pipelines)

What changed and why (one paragraph):

New skills/doctor-triage.md captures "doctor.sh says red — what now?" so a session reads it from disk instead of re-deriving it in Slack. Its subject is the conflation: my environment is wrong / the toolkit's own self-check is wrong / this red does not apply in my lane render identically in doctor's output, so Step 1 is establishing what is actually on the machine (file on the exact path doctor printed, which Studio Pro installs exist, whether each carries a bundled mx, OS/arch) rather than inferring from the message. It also carries the three toolchain lanes (bundled mx; the Linux-only CDN toolchain; the container lane, treated runtime-agnostically — Docker Desktop is not licensable for this team, Podman is what runs, and the skill notes that doctor.sh currently probes only docker as a known limitation rather than fixing it here), a derivation for which FAILs block instead of a list that would rot, and the VM/arch caveat that makes a sandboxed session's binary findings non-transferable. Per the authoring rules it hardcodes no version lists, clone paths or file inventories — two people in the source thread had the toolkit checked out at different paths — and each rule is paired with the concrete wrong output it prevents.

Field evidence — which real project this ran against / was observed in, and what it measured or fixed there:

The macOS onboarding thread of 2026-09-22: four people, one afternoon, three distinct failures treated as one.

1. The CDN mxbuild is a Linux ELF and cannot run natively on macOS at any Mendix version — the first confident answer, "install Studio Pro 10.24.18", would not have fixed it. One file call would have.
2. macOS Studio Pro was Beta through 10.x and ships no bundled …/Contents/modeler/mx; Mendix 11 is the first macOS build that carries one. On a Mac that is a platform requirement, not a toolkit preference.
3. doctor's own gate self-test was broken (fixed in fix(doctor): keep the model's real basename in the gate self-test scratch dir #128, c0ea53c): it renamed the scratch model copy against mprcontents' internal record of the real basename, so mxbuild bailed before writing any error file and the self-test reported fail (unreadable error file) — the string meaning the gate itself is broken — on a healthy gate.

Plus two lessons from the same thread, both in the skill: one colleague shipped with 2 FAILs open, correctly, and nobody else knew which two were ignorable (hence the N+M-lines-dispositioned completion bound); and a colleague diagnosing from a Linux ARM64 VM mounting a Mac folder produced findings that could not reproduce on the host.

• No client data anywhere in the diff
• Size cap: 11 files, 9 of them a one-line generated routing row each; the only hand-written files are the new skill, the TSV row and CHANGELOG.md
• Test tier reached: T0 — bin/render-routing.sh --check clean ("Routing surfaces in sync with the table; all skills routed or exempted. Baseline: 73341 words (budget 80000)"), which CLAUDE.md names as the correct scoped check for a routing change. bin/check-docs-numbering.sh verified by inspection against the new file (no <N>-step prose claim, no Gate <N> ordinals — grep returns nothing, so both its assertions are vacuously satisfied). tests/wave2/test-render-routing.sh and test-routing-tier.sh are the fixtures that cover this change and were not run — they would confirm the renderer/tier behaviour that --check already exercised on this exact table; happy to run either on request.
• For a new/changed instrument: n/a — no instrument changed, only a skill and the generated routing surfaces
• For a new skill: routing row added (bin/lib/skill-routing.tsv + bin/render-routing.sh)
• CHANGELOG.md line appended in this PR, crediting the thread
• No new bug entries

Routing row (group diagnose, tier ondemand, agents all, stages -):

doctor.sh reports FAIL or WARN, or someone asks whether a red setup line blocks them — check what is actually on the machine before naming a fix; a wrong-arch binary, a missing one and a broken self-check all read the same

New-file vs extend: surveyed README.md (both tables), ROUTING.md, skills/conversion-runbook.md (Prerequisites), skills/cloud-dev-environment.md, skills/tool-output-is-not-ground-truth.md and bin/doctor.sh's header. Nothing owns this trigger: the runbook's Prerequisites tells you to run doctor and assumes it came back clean, cloud-dev-environment.md is scoped to the ephemeral-container lane, and tool-output-is-not-ground-truth.md is the general principle for reading a model through tooling, not a setup-triage procedure. One skill, one situation.

🤖 Generated with Claude Code

https://claude.ai/code/session_0187r9bQWkZAEppyEqrDevjK

---

Generated by Claude Code