# `.env.example` does not contain placeholder values in production templates

- **Pattern:** `ab-000272` (`ai-slop-half-finished.dev-artifacts.placeholder-env-values`)
- **Severity:** low
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000272
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000272)

## Why it matters

Values like `STRIPE_SECRET_KEY=your_stripe_key_here` or `DATABASE_URL=TODO` in `.env.example` waste every new contributor's onboarding time. They cannot tell which format the real value takes, whether it is a test key, or what character length to expect. The file exists specifically to bootstrap environments, so a placeholder that communicates nothing defeats its purpose and often leads developers to paste real credentials into the wrong slot.

## Severity rationale

Low because these are template files, but placeholder tokens still slow onboarding and risk credential misplacement.

## Remediation

Replace placeholder tokens with recognizable example values that preserve format and prefix conventions. Use public Stripe test-mode prefixes, a canonical Postgres URL shape, and documented character counts. Fix at `.env.example`:

```
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

## Detection

- **ID:** `placeholder-env-values`
- **Severity:** `low`
- **What to look for:** Read `.env.example`, `.env.template`, `.env.sample` files. Count all env var declarations whose values match placeholder patterns: `your_api_key_here`, `your_secret_here`, `YOUR_KEY`, `YOUR_SECRET`, `xxxxxxxx`, `CHANGEME`, `change_me`, `replaceme`, `replace_me`, `TODO`, `FIXME`, empty string. EXCLUDE variables whose values are obvious patterns like `sk_test_xxx` or `postgresql://localhost:5432/dbname` (these are recognizable examples, not placeholders). Report the count of true placeholder values.
- **Pass criteria:** 0 true placeholder values in `.env.example` files. Recognizable example values are acceptable. Report: "Scanned X env template files, Y variables documented, 0 with placeholder values needing replacement."
- **Fail criteria:** At least 1 env variable in a template file has a `YOUR_X` / `TODO` / `CHANGEME` / empty value.
- **Skip (N/A) when:** No `.env.example`, `.env.template`, or `.env.sample` file exists.
- **Detail on fail:** `"2 placeholder env values: 'STRIPE_SECRET_KEY=your_stripe_key_here' and 'DATABASE_URL=TODO' in .env.example"`
- **Remediation:** Placeholder env values force every developer to guess what the real value should be. Use recognizable example values instead:

  ```
  # Bad: .env.example
  STRIPE_SECRET_KEY=your_stripe_key_here
  DATABASE_URL=TODO

  # Good: .env.example
  STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx
  DATABASE_URL=postgresql://user:password@localhost:5432/dbname
  ```

  Recognizable formats help developers understand what to paste where.

Taxons: placeholder-hygiene

HTML version: https://auditbuffet.com/patterns/ab-000272