Graceful failure with clear warnings

Severity: Recommended

Test during GIT-001 subagent run:

1. After successful run, try running with a required env var removed/unset
2. Observe behavior - does it crash or warn gracefully?
3. If it fails, evaluate error message quality

Verify env var usage:

1. For each variable in .env.example (or .env), grep the codebase to find where it's used
2. Document what each variable is for (e.g., DATABASE_URL → database connection in src/db.ts:12)
3. Flag any env vars that are defined but never referenced (stale)
4. Flag any env vars referenced in code but missing from example (undocumented)

Pass criteria:

• App shows clear warning indicating what's missing and what it's for
• OR app runs with degraded functionality and logs warnings
• All env vars are accounted for (used and documented)

Fail criteria:

• Cryptic stack trace with no indication of the problem
• Silent failure (app seems to run but features broken with no warning)
• Generic errors like Cannot read property 'x' of undefined
• Connection refused with no context
• Stale or undocumented env vars

Evidence to capture:

• Table of env vars → where used → purpose
• Sample error messages when vars missing

---