---
name: local-environment-doctor
description: "Diagnoses a broken local development setup by checking versions, paths, environment variables and caches in order of how likely each is to be at fault. Use when a project that worked before now fails to build, install or start locally, and the cause is probably versions, paths, env vars or caches. Do not use for production outages or application logic bugs. Related topics: coding, devops."
---

# Local Environment Doctor

Diagnoses a broken local development setup by checking versions, paths, environment variables and caches in order of how likely each is to be at fault.

## When to use

Use this skill when a project that worked before now fails to build, install or start locally, and the cause is probably versions, paths, env vars or caches. Do not use it for production outages or application logic bugs.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Quote the decisive line of the error and note when it began, using the recent-changes list.
3. Rank the candidate causes from most to least likely, using whether it works on other machines or in CI.
4. Give one read-only check per candidate and explain what each outcome means.
5. Propose a fix only for the confirmed cause, choosing the least destructive option and warning before deletion or reinstalls.
6. Provide a command that proves the fix worked and one habit that prevents a recurrence.

## Inputs

- **What fails** (longer free text)
- **Operating system** (choose one: macOS, Linux, Windows, Windows with WSL)
- **Project and tools** (longer free text)
- **What changed recently** (longer free text)
- **Works elsewhere** (choose one: Works on another machine, Works in CI, Never worked, Not sure)
- **Diagnostic output** (longer free text)

## Output

A ranked list of likely causes, each with a read-only check, then the fix for the confirmed cause, a verification command and one prevention habit.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Local Environment Doctor

Diagnose why my local setup is broken.

- What fails: {{What fails}}
- Operating system: {{Operating system}}
- Project and tools: {{Project and tools}}
- What changed recently: {{What changed recently}}
- Works elsewhere: {{Works elsewhere}}
- Diagnostic output: {{Diagnostic output}}

Read the error first and quote the line that matters. Then rank causes from most to least likely, given what changed and where it works. Check in this order: tool versions against what the project expects, the first copy of each tool found on the PATH, missing or stale environment variables, leftover caches and lockfile drift, permissions, and finally corrupted installs. For every candidate give one read-only command that confirms or rules it out and what each result means. Only after confirmation propose a fix, starting with the least destructive one, and warn before any command that deletes files or reinstalls. Never ask for a secret value; when a variable matters, ask only whether it is set. After the fix, give the command that proves it works and one habit that prevents a repeat.

## Pitfalls

- Deleting node_modules or the whole environment first, which erases the evidence and hides the real cause.
- Fixing the version in the shell while the editor or a script launches a different copy from another path.
- Pasting environment output that includes secret values into the conversation.