# Dev Doctor

> Claude Code dev doctor: workflow guidelines, best practices, instructions, and integration examples

- Skill: `uitbreidenos/dev-doctor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add uitbreidenos/dev-doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uitbreidenos/dev-doctor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: UitbreidenOS (https://skillmd.com/u/uitbreidenos)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/uitbreidenos/dev-doctor

---


# Dev Doctor

## When to activate
Activate when a user reports that "the app won't start", "the database isn't connecting", or when experiencing generic `ECONNREFUSED` or startup errors. Invoked via `/dev-doctor`.

## When NOT to use
Do not use for debugging specific syntax errors, failing unit tests, or logic bugs inside application code. This is strictly for *environment* and *infrastructure* health checks.

## Instructions
1. Pause whatever coding task you are currently on. You are now acting as a SysAdmin diagnosing a local developer environment.
2. Systematically check the following common failure points using shell commands:
    *   **Environment Variables:** Check if `.env.example` or `.env.template` exists. If it does, compare its keys against the actual `.env` file. Report any missing keys.
    *   **Ports in Use:** Look at the project's configuration (e.g., `docker-compose.yml`, `package.json` scripts) to find expected ports (e.g., 3000, 5432, 6379, 8080). Use `lsof -i :<port>` or `netstat -tuln | grep <port>` to check if those ports are already occupied by zombie processes.
    *   **Docker Daemon:** If the project uses Docker, run `docker info` to verify the Docker daemon is actually running.
    *   **Dependency Drift:** 
        * Node: Check if `node_modules` exists. Run `npm ls` or `yarn check` to see if dependencies need installing.
        * Python: Check if the virtual environment is activated and `pip freeze` matches `requirements.txt`.
3. Provide a clear, color-coded (using emojis) diagnostic report:
    *   🟢 Healthy
    *   🔴 Failing
    *   🟡 Warning
4. For any 🔴 Failing items, propose a direct fix (e.g., "Run `kill -9 1234` to free port 3000" or "Copy `.env.example` to `.env` and fill in `DATABASE_URL`"). Ask for permission before running the fix.

## Example
User: `/dev-doctor`
Claude: Running environment diagnostics...
*   🔴 **.env File:** Missing! Found `.env.example` but no `.env`.
*   🔴 **Ports:** Port 5432 is already in use by PID 8891 (looks like an older local postgres instance, not the docker container).
*   🟢 **Docker:** Daemon is running.
*   🟢 **Dependencies:** `node_modules` is present and up to date.

**Suggested Fixes:**
1. I can copy `.env.example` to `.env`.
2. I can kill PID 8891 to free up port 5432.
Shall I proceed with these fixes?