tools-only Use ultrathink to thoroughly analyze configuration patterns and potential runtime issues.
Purpose
Static code analysis (like /QA) cannot catch config-dependent runtime behavior. This command specifically audits environment variable usage to find issues that only manifest with production configuration.
Execution Strategy
Use the Task tool with subagent_type=Explore to scan systematically.
Phase 1: Discovery
Find all environment variable usages:
# Frontend env vars
grep -rn "NEXT_PUBLIC_" --include="*.ts" --include="*.tsx" src/ app/ lib/ hooks/ components/
# Backend env vars
grep -rn "process\.env\." --include="*.ts" --include="*.tsx" src/
grep -rn "os\.environ\|os\.getenv\|environ\.get" --include="*.py" .
# .env files
cat .env* 2>/dev/null | grep -v "^#"
Phase 2: Fallback Pattern Detection
CRITICAL: Find dangerous fallback patterns that activate when vars are empty.
# JavaScript/TypeScript fallbacks to localhost
grep -rn "|| ['\"]http://localhost" --include="*.ts" --include="*.tsx" .
grep -rn "|| ['\"]ws://localhost" --include="*.ts" --include="*.tsx" .
grep -rn "?? ['\"]http://localhost" --include="*.ts" --include="*.tsx" .
# Empty string fallbacks
grep -rn "|| ['\"]['\"]" --include="*.ts" --include="*.tsx" .
# Python fallbacks
grep -rn "\.get(.*localhost" --include="*.py" .
grep -rn "or ['\"]http://localhost" --include="*.py" .
Phase 3: Side Effect Tracing
For auth-related env vars, trace what happens on failure:
- Find token/auth clearing functions:
grep -rn "clearToken\|logout\|removeToken\|deleteToken" --include="*.ts" --include="*.tsx" .
- Find all callers of those functions:
# For each function found, trace callers
grep -rn "<function_name>" --include="*.ts" --include="*.tsx" .
- Check if network errors trigger auth clearing:
grep -rn "401\|403\|unauthorized" --include="*.ts" --include="*.tsx" . | grep -i "clear\|logout\|remove"
Phase 4: Link Validation
Find all static links and verify routes exist:
# Extract href values
grep -roh 'href="[^"]*"' --include="*.tsx" src/ app/ | sort -u
# Extract Link to values
grep -roh "to=['\"][^'\"]*['\"]" --include="*.tsx" src/ app/ | sort -u
# List all page routes
find app -name "page.tsx" -o -name "page.ts" | sed 's|app||;s|/page.tsx||;s|/page.ts||'
Compare extracted links against available routes. Flag any mismatches.
Output Format
Part A — Environment Variable Census
Total env vars found: X
- NEXT_PUBLIC_*: X vars
- Server-side: X vars
Env Vars with Fallbacks:
| Variable | Fallback Value | File:Line | Risk |
|----------|---------------|-----------|------|
| NEXT_PUBLIC_API_BASE | "http://localhost:8000" | lib/api.ts:5 | HIGH |
| ... | ... | ... | ... |
Part B — Dangerous Fallback Patterns
Finding #<N>
Variable: <NEXT_PUBLIC_*>
Location: <file:line>
Current Code:
const apiBase = process.env.NEXT_PUBLIC_API_BASE || "http://localhost:8000"
Issue: Falls back to localhost when empty - will fail in production
Fix:
const apiBase = process.env.NEXT_PUBLIC_API_BASE
if (!apiBase) throw new Error("NEXT_PUBLIC_API_BASE is required")
Part C — Auth Cascade Analysis
Token clearing functions found:
1. clearToken() in lib/auth.ts:45
Called by:
- onError(401) in lib/api.ts:78
- logout() in components/Header.tsx:23
- handleAuthError() in hooks/useAuth.ts:56
⚠️ WARNING: Network failure (401) triggers clearToken()
Path: fetch fails → 401 response → onError → clearToken → user logged out
Is this intentional? Verify auth cascade behavior.
Part D — Broken Links
Links not matching any route:
| Link | Found In | Suggested Fix |
|------|----------|---------------|
| /activity | components/Nav.tsx:34 | Create app/activity/page.tsx or remove link |
| /settings/advanced | ... | ... |
Part E — Recommendations
Before changing env vars:
1. Run: grep -rn "|| ['\"]http://localhost" to find fallbacks
2. Test with: NEXT_PUBLIC_API_BASE="" npm run dev
3. Check Network tab for localhost requests
Immediate fixes needed:
1. <file:line> - Remove localhost fallback
2. <file:line> - Add explicit error for missing config
Checklist
Before finalizing:
- All NEXT_PUBLIC_* vars cataloged
- All fallback patterns identified
- Auth cascade paths traced
- Static links validated against routes
- Each finding has specific file:line reference
- Each finding has concrete fix