Feature Flags Architect

Feature Flags Architect

End-to-end discipline for feature flags: classify them, ship them, ramp them, and retire them. Most teams treat flags as throwaway if-statements; this skill treats them as a controlled lifecycle with measurable debt.

When to use

• Adding a new flag and need a rollout plan
• Auditing a codebase for stale or orphaned flags
• Choosing a flag provider (LaunchDarkly vs GrowthBook vs Statsig vs Unleash vs Flipt vs build-your-own)
• Designing a kill-switch path for a risky launch
• Cleaning up flag debt before a release freeze
• Reviewing whether a feature should ship behind a flag at all

Core principle: flags are a lifecycle, not an if

request → design → ship → ramp → cleanup → archive

Flags that skip cleanup become debt: dead branches, stale defaults, untested code paths, unbounded blast radius. The three scripts in this skill enforce the lifecycle.

Quick start

# 1. Audit the repo for flag debt
python scripts/flag_debt_scanner.py --repo . --max-age-days 90

# 2. Plan a progressive rollout for a new flag
python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring

# 3. Verify every flag has a documented kill switch
python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md

The 4 flag types (taxonomy)

Different flag types have different lifespans and ownership. Misclassifying creates debt.

Only Release and Experiment flags should be on a debt-scanner watchlist. Operational and Permission flags are by design long-lived. See references/flag_taxonomy.md for decision tree.

The 3 Python tools

All three are stdlib-only. Run with --help.

flag_debt_scanner.py

Finds flags older than --max-age-days with low usage, suggesting candidates for cleanup.

python scripts/flag_debt_scanner.py --repo . --max-age-days 90 --format text
python scripts/flag_debt_scanner.py --repo . --max-age-days 60 --format json > debt.json

Detection heuristic: 1. Walk --repo for code references matching common flag-call patterns:

• flag("..."), isFlagEnabled("..."), featureFlag("..."), getFlag("...")
• client.variation("...", ...), unleash.isEnabled("..."), growthbook.feature("...")

2. For each unique flag identifier, find the oldest commit that introduced it (git log --diff-filter=A -S <name>). 3. Flag as DEBT if introduced > --max-age-days ago AND used in ≤--min-uses places.

Outputs flag name, age in days, file references, suggested action. JSON mode is CI-friendly.

rollout_planner.py

Generates a phased rollout schedule from population size, target percent, duration, and strategy.

python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring
python scripts/rollout_planner.py --population 50000 --target-percent 25 --duration-days 7 --strategy linear
python scripts/rollout_planner.py --population 1000000 --target-percent 100 --duration-days 30 --strategy log

Strategies:

• ring: 1% → 5% → 25% → 50% → 100%, evenly spaced. Default for risky launches.
• linear: constant rate per day. Default for medium-risk.
• log: rapid early, slow tail. Default for low-risk launches with confidence.
• cohort: by named cohort (internal → beta → free → paid → all).

Outputs a markdown table with date, percent, expected user count, abort criteria, and verification step per phase.

kill_switch_audit.py

Cross-references code-discovered flags against documentation to verify each has a kill switch path written down.

python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md
python scripts/kill_switch_audit.py --repo . --flag-doc runbooks/flags.md --format json

What it checks: 1. Every code-discovered flag has an entry in --flag-doc 2. Each entry declares: owner, type, kill-switch trigger, monitoring dashboard 3. Reports flags missing documentation (FAIL) or missing fields (WARN)

Use as a pre-merge gate before any new flag ships.

Provider chooser (5 + DIY)

Decision rules:

• <50 flags + no targeting → 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
• See references/provider_comparison.md for detail.

Workflows

Workflow 1: Ship a new feature behind a flag

1. Classify: which of the 4 flag types?
   → Release (most common for engineering work)
2. Run rollout_planner.py to design the ramp
3. Add flag entry to docs/feature-flags.md BEFORE writing code:
   - name, owner, type, kill-switch trigger, dashboard URL
4. Write the code with the flag
5. Run kill_switch_audit.py — must pass before merge
6. Deploy at 0%; verify kill switch works
7. Execute rollout schedule; abort if abort criteria met
8. At 100% for 7+ days: remove flag, delete dead branch, archive doc entry

Workflow 2: Quarterly flag cleanup

1. Run flag_debt_scanner.py --repo . --max-age-days 90 > debt.md
2. For each flagged item:
   a. Confirm it reached 100% (or was killed)
   b. Find the issue/PR that introduced it; verify owner agrees to remove
   c. Delete dead branches; remove flag config
   d. Run kill_switch_audit.py — should now show one fewer flag
3. Update CHANGELOG: "Removed N stale flags"

Workflow 3: Choose a provider

1. Estimate flag count (current + 12-month projection)
2. Required features:
   - Targeting rules (user, account, geo, %)?
   - A/B testing + stats?
   - Audit log / SOC2?
   - Self-hosting / data residency?
3. Pricing budget (MAU * cost-per-MAU)
4. See provider_comparison.md decision tree
5. Build a 30-day proof-of-concept before signing

Workflow 4: Design a kill switch

1. Identify the failure modes:
   - Latency spike (which threshold?)
   - Error rate spike (which threshold?)
   - Business metric regression (which threshold?)
2. Wire each to an abort:
   - Manual: dashboard link + on-call playbook
   - Automated: alert threshold flips flag back to 0%
3. Test the kill switch in staging BEFORE production rollout
4. Document in flag-doc; pass kill_switch_audit.py

References

• references/flag_taxonomy.md — 4 types, decision tree, ownership, lifespan
• references/provider_comparison.md — LaunchDarkly / GrowthBook / Statsig / Unleash / Flipt / DIY trade-offs
• references/rollout_strategies.md — ring / linear / log / cohort / geo, abort criteria, monitoring
• references/flag_lifecycle.md — request → design → ship → ramp → cleanup → archive

Slash command

/flag-cleanup — Run the full cleanup workflow on the current repo: scan for debt, generate a removal plan, audit kill switches.

Asset templates

• assets/flag_request_template.md — fill-in form for new flag requests (name, owner, type, kill switch, rollout plan)

Anti-patterns

• Permanent flag with `if (FLAG_FOO)` 50 places — should be a Permission flag with a runtime config, not a Release flag
• 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
• A/B test that ran 6 months — pick a winner; running indefinitely is debt
• Flags as feature toggles for cosmetic changes — ship via deploy, not flag

Verifiable success

A team using this skill should achieve:

• 100% of new flags pass kill_switch_audit.py at merge time
• flag_debt_scanner.py --max-age-days 90 returns ≤5 stale flags repo-wide
• Every flag has a documented owner, type, and kill switch
• Mean time to retire a Release flag: <60 days from 100% rollout

Feature flag request

Fill in every section before opening a PR that adds the flag.

Basics

• Name: <kebab-case-flag-name> (e.g., new-checkout-flow)
• Owner: <your-handle@team>
• Type: [ ] Release [ ] Experiment [ ] Operational [ ] Permission
• Created: <YYYY-MM-DD>
• Expected cleanup: <YYYY-MM-DD or "permanent">

Justification

Why a flag and not a direct deploy?

(Examples: risky launch, A/B test, kill-switch needed, gradual rollout, compliance requirement)

Rollout plan

Generated by rollout_planner.py. Paste output below.

<paste output here>

Kill switch

• Trigger: <concrete signal that flips the flag back to 0%>
• Threshold: <numeric threshold>
• Method: [ ] Manual via dashboard URL [ ] Automated via alert webhook
• Runbook: <link to on-call runbook>

Monitoring

• Dashboard: <URL>
• Key metrics to watch:
• <metric 1> baseline: <value>, abort threshold: <value>
• <metric 2> baseline: <value>, abort threshold: <value>

Code locations

• Decision point: <file:line> (single point of conditional)
• Provider used: <LaunchDarkly | GrowthBook | Statsig | Unleash | Flipt | DIY>
• SDK: <sdk version / config file path>

Tests

• [ ] Test for ON branch
• [ ] Test for OFF branch
• [ ] Kill-switch test in staging (verify flag flip works)

Cleanup criteria

When can this flag be removed?

(Example: at 100% rollout for ≥7 days with no incidents)

Pre-merge checklist

• [ ] kill_switch_audit.py passes
• [ ] flag-doc entry added with all required fields
• [ ] PR description links to this template
• [ ] Owner has write access to the provider dashboard
• [ ] Abort criteria are concrete numbers, not vague

Flag lifecycle

Every flag passes through 6 phases. Skipping any phase creates debt.

request → design → ship → ramp → cleanup → archive

Phase 1: Request

Triggered by an engineer or PM identifying a need.

Required:

• Flag name (kebab-case, descriptive: new-checkout-flow not flag1)
• Owner (named individual; not a team)
• Type (Release / Experiment / Operational / Permission)
• Justification (why a flag, not direct deploy?)
• Expected lifespan (days for Release, weeks for Experiment)

Tool: assets/flag_request_template.md

Reject the request if:

• It's a cosmetic change with no risk → ship via deploy
• It has no clear cleanup criteria → not a flag, refactor instead
• It duplicates an existing flag → reuse

Phase 2: Design

Before writing code. Document decisions.

Required artifacts:

• Entry in docs/feature-flags.md (or your flag registry) with: name, owner, type, kill switch, dashboard URL
• Rollout plan generated by rollout_planner.py
• Kill-switch trigger and runbook
• Abort criteria with concrete thresholds

Code location:

• Single point of decision (not 5 if (flag) scattered)
• Use a strategy/feature-toggle pattern at module boundary

# Good: one decision at module entry
if flags.is_enabled("new-checkout"):
    return new_checkout(request)
return legacy_checkout(request)

# Bad: flag check scattered through the function
def checkout(request):
    if flags.is_enabled("new-checkout"):
        validate_v2(request)
    else:
        validate_v1(request)
    if flags.is_enabled("new-checkout"):
        format_v2(request)
    else:
        format_v1(request)
    # ... many more

Phase 3: Ship

Deploy with flag at 0% in production, 100% in dev/staging.

Verification before merge:

• [ ] kill_switch_audit.py passes
• [ ] Both branches (on/off) covered by tests
• [ ] Provider dashboard shows the flag at 0%
• [ ] Kill switch tested in staging (flip to ON, observe; flip to OFF, observe)
• [ ] Monitoring dashboard linked from flag-doc entry

Common shipping mistakes:

• Default-to-true in production (skip the safety wheels)
• Test only the new path; assume the old path still works
• Forget to update the flag-doc

Phase 4: Ramp

Execute the rollout plan from rollout_planner.py. Hold each phase per rollout_strategies.md.

Decision points:

• After each phase: check abort criteria → hold | rollback | advance
• Communicate progress in team channel
• Update flag-doc with current percent and any abort events

Phase 5: Cleanup

Once at 100% (or experiment concluded with a winner picked), remove the flag.

Cleanup checklist:

• [ ] Flag at 100% for ≥7 days (Release flags) OR test concluded (Experiment)
• [ ] Owner confirms no rollback risk
• [ ] Code change: delete the conditional, keep the new branch, delete the old branch
• [ ] Delete the flag in the provider dashboard
• [ ] Mark the flag-doc entry as ARCHIVED with date and PR link
• [ ] Add to CHANGELOG: "Removed feature flag: <name>"

Common cleanup mistakes:

• Removing the flag from code but forgetting the provider config (orphaned)
• Removing both branches (keep the new one)
• Not updating flag-doc (audit trail lost)
• Not running tests after removal (latent break)

Phase 6: Archive

Move the flag-doc entry to an archive section. Keep the audit trail.

## Archived

### new-checkout-flow [removed 2026-04-12, PR #1234]
- Owner: jane@team
- Type: Release
- Lifespan: 38 days from request to removal
- Outcome: Shipped at 100%; no incidents

Lifecycle automation

SLAs by phase

Worked example

Day 0: Engineer files request: new-search-relevance Release flag, owner @bob, expected 21-day rollout.

Day 2: Design done. flag-doc entry created. rollout_planner.py output: ring strategy, 5 rings over 14 days. Kill-switch: any drop in CTR > 5%, set flag to 0% via provider API.

Day 4: Code shipped, flag at 0%. kill_switch_audit.py green. Smoke test passes.

Day 5: Ring 1 — 1% rollout. CTR within bounds. Hold 48h.

Day 7: Ring 2 — 5%. p99 latency +5% (within bounds). Hold 48h.

Day 9: Ring 3 — 25%. CTR +2% — winning. Hold 48h.

Day 11: Ring 4 — 50%. CTR +2.5%. Hold 48h.

Day 13: Ring 5 — 100%. Hold 7 days for stability.

Day 20: Cleanup PR opens — remove conditional, delete old branch.

Day 21: PR merged. Flag deleted in provider. flag-doc entry archived.

Total elapsed: 21 days. This is the target.

When the lifecycle breaks

Flag taxonomy — the 4 types

Misclassifying a flag is the root cause of flag debt. Pick one type at the moment you create the flag.

Decision tree

Is the flag intended to be permanent (entitlement, plan tier, role-based access)?
├── YES → Permission flag
└── NO → Will it eventually be removed?
    ├── Will it be removed when feature is fully shipped?
    │   └── Yes → Release flag
    ├── Will it be removed when an A/B test concludes?
    │   └── Yes → Experiment flag
    └── Will it remain as a circuit breaker / safety toggle?
        └── Yes → Operational flag

1. Release flag

Purpose: Hide an unfinished or risky feature in production while it's being built or rolled out.

Examples:

• new-checkout-flow — gating a UI rewrite
• payment-v2-engine — gating backend rewrite during cutover
• enable-search-relevance-v3 — A/B test of new ranking

Anti-pattern: Release flag still at 100% in code 6+ months later. The branch the flag protects is dead code; remove it.

2. Experiment flag

Purpose: Run an A/B test or multivariate experiment.

Examples:

• homepage-headline-v2 — testing new copy
• pricing-page-monthly-vs-annual-default — testing default toggle
• onboarding-checklist-vs-tour — testing onboarding pattern

Anti-pattern: Experiment running for 6 months because no one decided to call it. Either declare a winner or kill the test.

3. Operational flag

Purpose: Circuit breakers, kill switches, performance toggles. Designed to be flipped during incidents.

Examples:

• enable-rate-limit-v2 — kill switch if v2 misbehaves
• disable-recommendations-engine — emergency cutoff
• use-fallback-search — degraded mode toggle

Anti-pattern: Operational flag that no one knows how to use during an incident. Document the trigger and runbook.

4. Permission flag

Purpose: Entitlements per user/account/plan/role. Permanent by design.

Examples:

• feature.advanced-analytics — enterprise-only
• feature.export-csv — paid plans only
• role.admin-dashboard — admin-only UI

Anti-pattern: Permission flags stored in a flag provider with per-user targeting rules. Move them to your entitlements system; they're not feature flags.

Classification matrix

When you can't decide, ask:

If none fit: you don't need a flag. Either ship the feature directly via deploy, or use a different mechanism (config, env var, role).

Ownership rules

• Every flag must have a named owner at creation
• When the owner leaves, the flag is reassigned within 30 days or removed
• Release flags lapse to the team's tech-debt owner if not reassigned

Lifespan SLAs

Provider comparison

Five mainstream providers + DIY. Pick based on flag count, targeting needs, compliance, and self-hosting requirements.

At-a-glance matrix

When to choose each

LaunchDarkly

Choose if:

• Enterprise team with 100+ flags across many services
• Compliance requires SOC2 / ISO 27001 / FedRAMP audit logs
• Need fine-grained targeting (cohorts, custom attributes, percentages by attribute)
• Need experimentation + targeting + audit in one platform
• Budget for enterprise tooling ($20-100k/year typical)

Avoid if:

• Small team / <50 flags (overkill)
• Strict data residency (no on-prem; relays only)
• Low budget

GrowthBook

Choose if:

• Mid-market team that wants OSS option for self-hosting
• Need built-in A/B testing with proper stats (frequentist + Bayesian)
• Want SQL-based experimentation (define metrics from your warehouse)
• Self-host on k8s or run their hosted Cloud

Avoid if:

• Need real-time targeting at edge (use LD or Statsig)
• Need enterprise audit features (Cloud only)

Statsig

Choose if:

• Growth/product team for whom experimentation is the core use
• Need advanced stats (CUPED, sequential testing)
• Want generous free tier (good for early-stage)
• Want best-in-class metric library and platform-side experimentation logic

Avoid if:

• Strict data residency / self-host requirement (no on-prem option)
• Don't need experimentation, just toggles (overkill)

Unleash

Choose if:

• OSS-first culture; want to self-host
• Dev-friendly with good SDKs and a clean API
• Don't need full A/B testing platform
• Need Open Source license for compliance (Apache 2)

Avoid if:

• Need experimentation + stats out of the box
• Need enterprise-grade audit (Enterprise tier only)

Flipt

Choose if:

• Lightweight needs, <100 flags
• k8s-native (Flipt is operator-friendly)
• Want pure OSS, no commercial component
• Don't need A/B testing

Avoid if:

• Need targeting beyond simple boolean rules
• Need experimentation
• Need analytics or audit features

DIY (env vars / config file)

Choose if:

• <50 flags total
• No targeting beyond enabled: true/false
• No A/B testing needs
• Want zero external dependencies
• Strict cost control

Implementation:

# config/flags.yaml
flags:
  new-checkout: { enabled: true, owner: jane@team }
  payment-v2:   { enabled: false, owner: bob@team, kill_switch: PagerDuty alert "payment-v2 SEV1" }

Or env-var based:

FLAG_NEW_CHECKOUT=true
FLAG_PAYMENT_V2=false

Avoid if:

• Flag count growing past 50
• Need percentage rollouts (you'll re-implement provider logic poorly)
• Need audit log (compliance)
• Multiple teams / multiple deploy cadences

Cost rule of thumb

Migration paths

Easy migrations:

• DIY → Unleash / Flipt (similar simple model)
• Unleash ↔ GrowthBook (similar feature surface)

Hard migrations:

• LaunchDarkly → anywhere (proprietary targeting language)
• Statsig → anywhere (proprietary experimentation logic)

Lock-in mitigation: Wrap your provider behind an interface in code:

interface FlagProvider {
  isEnabled(name: string, context?: UserContext): boolean;
  getValue<T>(name: string, defaultValue: T, context?: UserContext): T;
}

Swap providers by writing a new adapter, not by rewriting every call site.

Build-vs-buy threshold

Buy a provider when:

• Flag count > 50
• Multiple teams need to manage flags independently
• Targeting needs include percentages, cohorts, or custom attributes
• Compliance requires audit log
• Need real-time updates without redeploy

Build (DIY) when:

• All of the above are NO

Selection checklist

Before signing a contract:

• [ ] Estimate flag count over 12 months
• [ ] List required targeting dimensions (user/account/geo/%/custom)
• [ ] Confirm SDK availability for every language in your stack
• [ ] Check edge latency (p99 < 50ms for prod)
• [ ] Verify failure mode if provider is unreachable (default-to-safe)
• [ ] Confirm SOC2 / data residency if needed
• [ ] Run a 30-day proof-of-concept; measure actual cost at projected MAU

Rollout strategies

Pick a strategy by risk, not by preference. Higher-risk launches get slower, more granular ramps.

The 4 strategies

1. Ring (canary) — risky launches

1% → 5% → 25% → 50% → 100%

Phases: 1. 0% (deploy) — code ships dark; verify it deploys without flag turned on 2. 1% — internal users + low-traffic cohort; full metric verification 3. 5% — broader smoke test; watch for tail-of-distribution issues 4. 25% — significant load; performance and infra checks 5. 50% — half-and-half; perfect for A/B comparison 6. 100% — fully on; hold 7 days before removing flag

Abort triggers per ring:

• Error rate > baseline + 1pp
• p99 latency > baseline × 1.2
• Business metric regression (conversion, retention) > baseline × 0.95

2. Linear — medium risk

Constant percent-per-day until target.

Example: 100% over 10 days = 10% per day.

3. Log (front-loaded) — low risk

Fast early ramp, slow tail. Reaches majority of population in first 1/3 of duration.

4. Cohort — entitlement-aware

Named segments rolled in order: internal → beta → free → paid → all

Order rules: 1. Internal first — your own team finds bugs cheaply 2. Beta opt-in users — they expect rough edges 3. Free tier — broader signal at lower commercial risk 4. Paid plans — most valuable users last (or first for premium features) 5. All — flag fully on; remove flag

Geo-staged variant

For internationally-distributed products, layer geo on top of any strategy:

Phase A: 100% in NZ/AU (low-traffic, English, off-business-hours US)
Phase B: 100% in EU (test data residency / GDPR paths)
Phase C: 100% in US (high traffic; full validation)

Useful for catching i18n, timezone, and regional infrastructure issues before peak load.

Abort criteria

Hard-coded thresholds that auto-flip the flag back to 0% (or trigger paging):

Automate: wire each threshold to a webhook that sets the flag to 0% via provider API.

Verification per phase

At each phase, confirm:

1. Health metrics are within abort thresholds 2. Business metrics match or exceed control 3. Logs show no new error patterns 4. User reports (support tickets) show no spike for the affected feature 5. Ops on-call acknowledges no anomalies

If any signal is off, hold the phase. Don't advance on schedule alone.

Hold-time rules

• Off-hours hold time doesn't count toward bake-in (e.g., a phase started Friday 6pm in PST is held until Monday 9am)
• Weekend rollouts require explicit owner approval and on-call coverage
• Holiday rollouts require VP-level approval

Common mistakes

Tools

• scripts/rollout_planner.py — generates a markdown plan
• Provider dashboards — for execution and real-time abort
• Metrics dashboard linked from flag-doc entry
• On-call runbook with kill-switch trigger words