---
name: env-config-doctor
description: Audit environment variables across .env files, code usage, and deploy configuration before they bite. Use when a deploy fails with a missing or malformed config value, when environments drift apart, or before adding a new environment - finds used-but-unset vars, set-but-unused vars, and shape mismatches between environments.
---

# Env Config Doctor

## When to use

- "Works locally, 500s in production" with config in the stack trace
- Before promoting a change to a new environment
- Periodic drift check on a project with several .env files

Do NOT print secret values. Names and shapes only - a report that
leaks a value is worse than the drift it found.

## The three-way diff

Build three sets, then compare them pairwise:

1. **Used in code**: every var the code reads (process.env, import.meta,
   config loaders). Note where each is read and whether it has a
   fallback default.
2. **Set somewhere**: every var defined in .env files, deploy config,
   CI secrets lists, container definitions. Record which file or
   system sets each - never the value.
3. **Documented**: every var in the README, .env.example, or setup
   docs.

## Findings to report

- **Used but unset**: code reads it, nothing sets it in this
  environment. This is the 500 waiting to happen.
- **Set but unused**: defined but never read - stale config that
  confuses the next person. Mark for removal, do not remove.
- **Undocumented**: set and used, but missing from .env.example -
  the next setup will miss it.
- **Shape mismatch**: same var, different shape across environments -
  URL with and without a path, port as string vs number, boolean as
  "1" vs "true". Validate shape, not just presence.
- **Unreadable sources**: every config source you could not inspect
  (locked deploy dashboards, CI secrets you cannot list). A var is
  never "unset" in an environment you could not read - it is unknown,
  and the report names which sources were out of reach.

## Output format

One table per finding class, columns: variable, where used, where set,
what is wrong, suggested fix. End with a count summary and the single
most dangerous finding called out by name.

## Hard boundaries

- Never print, copy, or exfiltrate secret values - names and shapes
  only.
- Never "fix" drift by editing env files yourself; report and let the
  owner decide which environment is right.
- Treat a missing fallback as a finding only when the code crashes or
  misbehaves without it; some vars are legitimately optional.
