Dev Env Doctor

"Works on my machine" is a diagnosis waiting for a method. This skill debugs broken development environments — builds that fail on one laptop, tests green in the pipeline and red locally, tools that stopped working after an update — by bisecting the difference between an environment that works and the one that does not. It fixes the machine in front of it, then patches the project so the next machine never gets sick the same way.

When to use this skill

• Setup instructions fail on a fresh machine or a new teammate's laptop
• A build or test passes in one environment and fails in another
• Something worked yesterday and broke after an upgrade, an update, or "nothing changed"
• Recurring environment folklore ("just delete the cache and reinstall") needs a real cause

Workflow

1. Capture the failure verbatim: the exact command, full output, and exit code — not a paraphrase. Then establish the reference point: where does this work (a colleague's machine, the pipeline, last week)? The whole method is diffing sick against healthy.
2. Interrogate the layers in order, cheapest first: tool versions (runtime, package manager, compiler) and which binary actually resolves on the path through version-manager shims; then project state (is the lockfile respected? were dependencies installed against this runtime?); then environment variables and local config overrides; then caches and generated artifacts; finally the OS layer — architecture, shell profile, file permissions, case sensitivity.
3. Diff, don't meditate. Collect the same facts from the healthy environment and compare mechanically: version outputs, path resolution, relevant variables, lockfile hashes. The discrepancy list is short, and the culprit is usually on it.
4. Change one variable, re-run, record. Resist the shotgun (reinstall everything, reboot, re-clone) until single-variable tests have failed you. The shotgun often works — and teaches nothing, and will not save the next person.
5. Name the root cause in one sentence that includes the mechanism: "the shell profile pins an older runtime ahead of the version manager, so dependencies resolved against the wrong ABI." If you cannot write that sentence, you have a workaround, not a cause — label it honestly.
6. Fix the class, not the instance. Encode the cure into the project: pin the runtime version where the version manager reads it, add the missing prerequisite to setup docs, make the build fail fast with a clear message when the environment is wrong, or script the doctor check itself.
7. Verify like a newcomer: run the project's setup from the top in a clean shell (or a clean checkout when feasible) and confirm the original failing command now succeeds.

Output format

Symptom: <command + one-line failure>
Healthy reference: <where it works>
Diffs found: <version/path/env discrepancies, as a mechanical list>
Root cause: <one sentence with mechanism — or "workaround only", stated plainly>
Fix applied: <the local remedy>
Prevention shipped: <pin/doc/check added to the project, with file paths>

Guardrails

• Never run destructive resets (delete directories, reinstall toolchains, wipe config) without stating what will be lost and getting consent; convenience is not consent.
• Full command output goes into the record — truncating "irrelevant" warnings deletes the clue about half the time.
• One change per test cycle while diagnosing; batch fixes only after the cause is named.
• A fix that cannot survive the question "why does that work?" is quarantined as folklore, and the investigation stays open in spirit — note it for the next occurrence.
• Prevention is part of done: if the project leaves this session no easier to set up correctly than before, the doctor only treated a symptom.