Env Doctor

Env Doctor

Diagnoses project environment and startup failures systematically.

When to Use

• When the user says "it won't start", "I'm getting errors", "my environment is broken"
• When a build, test, or dev server fails unexpectedly
• When setting up a project on a new machine

Process

1. Identify the failure: Read the error output carefully

2. Check prerequisites:

   • Runtime versions (Node.js, Python, Go, etc.) — compare to project requirements
   • Package manager state (node_modules exists? venv activated?)
   • Required environment variables (check .env.example, .env, config files)
   • Required system tools (git, sqlite3, docker, etc.)
   • Required services (database, Redis, API keys)

3. Diagnose common issues:

   • Missing dependencies → suggest install command
   • Version mismatch → show required vs actual
   • Missing env vars → list what's needed and where to get values
   • Port conflicts → identify what's using the port
   • Permission errors → identify the restricted resource
   • Stale cache/build artifacts → suggest clean commands

4. Report findings in this format:

   ❌ Problem: [what's wrong]
   💡 Cause: [why it's happening]
   ✅ Fix: [exact command or step to resolve]
   

5. Offer to fix: If the fix is safe and reversible, offer to run it

Rules

• Check the simplest causes first (missing install, wrong directory, typo)
• Never suggest destructive fixes without confirmation
• If multiple issues exist, fix them in dependency order
• Verify the fix worked before moving on