Env Doctor Advanced

The Problem

The deploy works locally. The container exits immediately in production. You spend 45 minutes chasing the error before discovering that docker-compose.yml passes env_file: .env but the production docker run command doesn't. 14 variables are missing at runtime. Then you find that the .env file contains an AWS secret key AND is committed to git — a separate critical issue nobody flagged.

Environment configuration isn't one file — it's five layers that interact invisibly: local .env files (.env, .env.local, .env.production), shell profiles (.bashrc, .zshrc), CI/CD configs (GitHub Actions secrets, GitLab variables), Docker environments (Dockerfile ENV, docker-compose env_file), and runtime configs (package.json engines, pyproject.toml requires-python). A variable can be defined in Layer 2 but missing in Layer 3, and the developer who edited Layer 2 will swear they "already fixed it."

What You Get

• Five-layer environment inventory — locates all env files, shell profiles, CI configs, Docker configs, and runtime configs; counts variables per layer; checks git tracking status of each
• Variable gap analysis — cross-references required (from .env.example/README) vs. defined (in .env) vs. referenced (in code) vs. injected (in CI) to find missing, inconsistent, and orphaned variables
• Security audit — detects committed secrets (AWS keys, GitHub PATs, OpenAI keys, private keys), weak defaults (localhost in production), client-prefix leakage (NEXT_PUBLIC_, VITE_), and exposed credentials in CI logs
• Precedence deep-dive — diagnoses the #1 hidden bug source: same variable defined in multiple layers, with the wrong layer winning (real process env → .env.local → .env.<NODE_ENV> → .env)
• Version compatibility check — compares declared vs. runtime versions for Node.js engines, Python requires-python, Docker base image tags, and CI runner defaults
• Path and filesystem audit — catches hardcoded absolute paths, CRLF line endings on WSL, symlink issues, and non-interactive shell sourcing failures

Why This Beats Prompting It Yourself

Checking "is DATABASE_URL defined?" only tests Layer 2. The Environment Doctor compares all five layers simultaneously and finds the gaps between them: defined in Docker but missing in CI, defined in .env but overridden by .env.local, defined in shell profile but invisible in non-interactive shells (cron, CI, systemd). The precedence analysis catches the single most common "I changed my .env but nothing happened" cause — a higher-precedence layer shadowing the edit.

Example Session

You: "The container exits immediately in production. Works fine locally. Here's my docker-compose.yml and .env."

Agent:

ENVIRONMENT DIAGNOSIS REPORT
════════════════════════════

CRITICAL ISSUES
───────────────
Issue                        Location            Impact
───────────────────────────  ──────────────────  ────────────────────────────
14 env vars missing in       docker run command  Container exits at import
production runtime                               (KeyError on DATABASE_URL)
AWS secret key (AKIA...) in  .env + git history  Credential exposure — rotate
.env — git tracked                               immediately

ROOT CAUSE CHAIN
────────────────
1. docker-compose.yml passes env_file: .env ✅
2. Production uses docker run without --env-file ❌ (missing 14 variables)
3. Code: config.py does os.environ["DATABASE_URL"] with no default
4. Result: KeyError at import → instant container exit

SECURITY FINDINGS
─────────────────
Finding                      File    Risk
───────────────────────────  ──────  ───────────────────────────
AWS access key in plaintext  .env:7  CRITICAL — committed to git
.env tracked by git          root    HIGH — all secrets exposed

ENVIRONMENT SUMMARY
───────────────────
Layer                Variables  Missing  Inconsistent
───────────────────  ─────────  ───────  ────────────
Local (.env)         23         2        1
CI/CD                18         5        3
Docker               15         0        0
Runtime (code refs)  26         —        —

RECOMMENDED FIX ORDER
─────────────────────
1. Rotate AWS key immediately (credential exposure)
2. Purge git history: git filter-repo --invert-paths --path .env
3. Add --env-file to production docker run command
4. Add config validation at startup (fail fast with clear message)

Use Cases

• Production debugging — diagnose "container exits immediately" or "app crashes on startup" errors that smell like missing config
• New developer onboarding — prepare a validated fresh-machine setup checklist
• Pre-deploy environment audit — catch missing variables and security issues before deploying to staging or production
• CI/CD debugging — find variables that exist locally but are never injected into CI pipelines
• Secret hygiene audit — scan all env layers for exposed credentials, weak defaults, and client-prefix leakage

Known Limitations

This skill is read-only — it never modifies .env files, secrets, or configuration. Proposed fixes go to the user for review. It cannot detect secrets injected at runtime by external vault systems (HashiCorp Vault, AWS Secrets Manager) that aren't referenced in any config file.