feature-flags-architect

---
name: feature-flags-architect
description: Use when adding, retiring, or auditing feature flags: rollout plans, kill switches, stale flag debt, or choosing a flag provider (LaunchDarkly, GrowthBook, Statsig, Unleash, Flipt).
category: Engineering
version: 1.0.0
tools: []
---

# Feature Flags Architect

Manage feature flags through a controlled lifecycle — request → design → ship → ramp → cleanup → archive — rather than throwaway `if`-statements. Flags that skip cleanup become debt: dead branches, stale defaults, untested code paths, unbounded blast radius.

## Use when
- Adding a new flag and needing a rollout plan
- Auditing for stale or orphaned flags
- Choosing a flag provider (LaunchDarkly, GrowthBook, Statsig, Unleash, Flipt, or DIY)
- Designing a kill-switch path for a risky launch
- Cleaning up flag debt before a release freeze
- Deciding whether a feature should ship behind a flag at all

## The 4 flag types
Misclassifying a flag creates debt — each type has a different lifespan and owner.

| Type | Purpose | Typical lifespan | Owner | Cleanup trigger |
|---|---|---|---|---|
| Release | Hide unfinished features in production | days–weeks | Eng | 100% rollout reached |
| Experiment | A/B test variants | weeks | Product/Marketing | Test concluded; winner picked |
| Operational | Circuit breakers, perf toggles, kill switches | months–years | Eng/SRE | Replaced by autoscaling/feature retirement |
| Permission | Entitlements per user/account/plan | years (permanent) | Product | Plan/role removed |

Only Release and Experiment flags belong on a stale-flag watchlist — Operational and Permission flags are meant to be long-lived.

## Flag-debt review
When asked to find stale flags: identify flag references in code or docs (patterns like `flag("...")`, `isFlagEnabled(...)`, `client.variation(...)`, `unleash.isEnabled(...)`, `growthbook.feature(...)`), estimate each flag's age from when it was introduced, and flag as debt anything older than roughly 90 days that's used in very few places. For each debt candidate, confirm it reached 100% rollout (or was killed), identify the owner, and recommend removal.

## Rollout strategies
Plan a phased rollout from population size, target percent, duration, and one of:
- **Ring** — 1% → 5% → 25% → 50% → 100%, evenly spaced; default for risky launches
- **Linear** — constant rate per day; default for medium-risk
- **Log** — rapid early ramp, slow tail; default for low-risk launches with confidence
- **Cohort** — by named cohort (internal → beta → free → paid → all)

Produce a schedule with date, percent, expected user count, abort criteria, and a verification step per phase.

## Kill-switch audit
Every flag needs a documented entry: owner, type, kill-switch trigger, and monitoring dashboard. Before any new flag ships, confirm the entry exists and is complete — treat a missing kill switch as blocking, not a nice-to-have.

## Provider chooser

| Provider | Best for | Pricing model | Lock-in risk | OSS option |
|---|---|---|---|---|
| LaunchDarkly | Enterprise, complex targeting, audit/compliance | Per-MAU, expensive | High | No |
| GrowthBook | Mid-market, A/B testing focused, OSS-friendly | Per-MAU + OSS | Low | Yes (self-host) |
| Statsig | Growth/product teams, advanced experimentation | Free tier + per-MAU | Medium | No |
| Unleash | OSS-first, self-hosted, dev-friendly | OSS + Enterprise | Low | Yes |
| Flipt | Lightweight, k8s-native, simple needs | OSS-only | None | Yes |
| DIY | Under 100 flags, no targeting, full control | None | None | N/A |

Decision rules:
- Fewer than 50 flags and no targeting needed → DIY with config file or env vars
- Need analytics + experimentation → Statsig or GrowthBook
- Compliance/SOC2 audit logs required → LaunchDarkly
- Self-hosting required (data residency / air-gapped) → Unleash or Flipt

## Workflows

**Ship a new feature behind a flag** — classify the flag type (usually Release) → design the rollout ramp → document the flag (name, owner, type, kill-switch trigger, dashboard) before writing code → write the code → confirm the kill-switch entry is complete → deploy at 0% and verify the kill switch works → execute the rollout schedule, aborting if abort criteria are met → after 7+ days at 100%, remove the flag, delete the dead branch, and archive the doc entry.

**Quarterly flag cleanup** — review flags older than roughly 90 days → for each, confirm it reached 100% (or was killed), identify the owner, get agreement to remove, delete dead code and flag config → recheck the kill-switch audit → report how many stale flags were removed.

**Choose a provider** — estimate flag count now and in 12 months → list required features (targeting rules, A/B testing + stats, audit log/SOC2, self-hosting) → estimate budget (MAU × cost-per-MAU) → apply the decision rules above → recommend a 30-day proof-of-concept before signing.

**Design a kill switch** — identify failure modes (latency spike, error-rate spike, business-metric regression) and their thresholds → wire each to an abort path, manual (dashboard + on-call playbook) or automated (alert flips the flag back to 0%) → test the kill switch in staging before production rollout → document it and confirm it passes review.

## Anti-patterns
- A "permanent" flag with `if (FLAG_FOO)` in 50 places — should be a Permission flag with runtime config, not a Release flag
- A flag with no owner — when the original engineer leaves, no one cleans it up
- No kill switch documented — when the feature breaks, no one knows how to disable it
- An A/B test that ran 6 months — pick a winner; running indefinitely is debt
- Using flags as toggles for purely cosmetic changes — ship those via deploy, not flag

## Success targets
- 100% of new flags pass kill-switch review at merge time
- No more than roughly 5 stale flags (over 90 days old, low usage) outstanding repo-wide
- Every flag has a documented owner, type, and kill switch
- Mean time to retire a Release flag: under 60 days from 100% rollout
</content>