Feature Flags Architect

---
name: feature-flags-architect
description: Use when setting up or cleaning up feature flags. Triggers on "feature flags", "LaunchDarkly", "Statsig", "flag cleanup", "gradual rollout".
---

# Feature Flags Architect

Feature flags solve real problems (gradual rollouts, kill switches, permissions, experiments) and create new ones (flag debt, untested code paths, performance overhead, security gaps). Solving the right problems requires discipline most teams skip.

## Required inputs

1. **Team size + deploy cadence** — solo daily deploys vs. team weekly
2. **Stack** — language, framework, vendor preference (LaunchDarkly / Statsig / Unleash / build own)
3. **Use cases** — release, ops, permission, experiment (you may have all four)
4. **Current state** — no flags yet, or 50 flags nobody understands

## Output

### Flag taxonomy
Four types, each with different lifecycle:

- **Release flags** — TTL 1-4 weeks. Kill within 30 days of full rollout.
- **Ops flags** (kill switches, rate limit overrides) — permanent. Owned by on-call team.
- **Permission flags** (gate features by plan/role) — permanent. Owned by product team.
- **Experiment flags** — TTL = experiment duration + 2 weeks for analysis. Auto-cleanup hook.

### Naming convention
`{type}.{owner}.{feature}` — e.g., `release.checkout-team.new-payment-flow`

The owner prefix is load-bearing — when the cleanup script runs, you know who to ping.

### Required metadata per flag
- Owner (named human, not team)
- Type (from taxonomy above)
- Description (1 sentence — what does ON mean)
- Kill criteria (the condition that ends the flag)
- Created date
- Expected removal date (for release/experiment flags)

### Ownership and review
- Every flag has 1 named owner
- Monthly review: flags past expected removal → either remove or extend with reason
- Quarterly: ops flags reviewed for "is this kill switch still needed"

### Code patterns
- Wrap flag check in named function so removal is grep-able
- Avoid nested flag checks (`if flagA and flagB` is hard to remove)
- Test both branches in CI (or document why one is untested)
- For experiments: log the variant, not just the outcome, for analysis

### Cleanup process
- Weekly script: list flags past expected removal date
- Owner gets ping; they either remove or update expected date with reason
- Quarterly: leadership review of total flag count + age distribution

## Anti-patterns
- "Temporary" flags that live for 2 years
- Flags with no owner ("the team")
- A single flag that gates 30 different behaviors
- Using flags for what should be config
- Experiment flags that never get cleaned up (and contaminate future experiments)

## When to NOT use a flag
- Behavior is permanent — make it config
- The "off" branch isn't tested — that's not a flag, that's untested code with extra steps
- Change is small + low-risk + easy to roll back — skip the flag, deploy direct