Feature Flag Manager

---
name: feature-flag-manager
description: |
  Trigger when the user asks to add a feature flag, set up gradual rollout,
  or build a kill switch. Phrases: "feature flag", "feature toggle",
  "gradual rollout", "kill switch", "LaunchDarkly", "Unleash", "A/B flag".
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(pnpm add *)
---

# Feature Flag Manager

Add feature flags the right way - percentage rollouts, user targeting,
kill switches, and clean removal once a feature is fully launched. Prevents
flags from becoming permanent tech debt.

## Prerequisites

- Flag provider chosen (LaunchDarkly, Unleash, ConfigCat, Flagsmith, or
  homegrown)
- Naming convention agreed (e.g. `<area>_<feature>_enabled`)
- A place to track flag lifecycle (spreadsheet, Linear, flag dashboard)

## Steps

1. **Name the flag for its lifecycle.** Three common types:
   - **Release flag** - gates an in-flight feature; removed after launch
   - **Experiment flag** - A/B test; removed when winner is picked
   - **Ops flag** - kill switch or circuit breaker; kept indefinitely
   Name them so the type is obvious: `release_new_checkout`,
   `exp_signup_v2`, `ops_disable_webhooks`.

2. **Wrap the flag check in a helper, not inline:**
   ```ts
   // Bad: scattered client.variation() calls everywhere
   // Good: one helper per flag so the check is typed and searchable
   export function isNewCheckoutEnabled(userId: string): boolean {
     return flagClient.variation('release_new_checkout', userId, false)
   }
   ```
   Default value (`false` here) matters - it is what runs if the flag
   service is down.

3. **Gradual rollout plan.** For release flags:
   - 1% internal / employees
   - 10% beta users for 24 - 48 hours, watch error rates
   - 50% rollout, watch again
   - 100%, bake for a week
   - Remove the flag

4. **Kill switch for every risky integration.** Third-party API, new
   payment path, expensive compute - wrap it in an ops flag so you can
   disable it in seconds without a deploy.

5. **Build-time flags vs runtime flags.** Runtime is the default (change
   without redeploying). Build-time is fine for dead-code elimination of
   large features that are not shipping yet.

6. **Clean up religiously.** Every flag has a removal ticket filed the
   same day it is created. Expiry date in the flag dashboard. Weekly
   review of flags older than 90 days.

7. **Observability.** Log which variation each user got. Include the flag
   state on error reports so you can answer "did this user have the new
   code path?" without guessing.

## Patterns that work

- Typed flag helpers so TypeScript fails when a flag is renamed
- Default-off for new features, default-on for kill switches
- Flag state cached in memory with a short TTL (1 - 5 minutes) to avoid
  one network call per check
- Local overrides for dev so engineers can force-enable without the dashboard

## Anti-patterns

- Nested flags (flag A only checked if flag B is true) - debugging nightmare
- Flags in hot paths with no caching
- Feature flags used as config (use a config system instead)
- Flags that live forever because no one owns cleanup

## Output

- Flag helper module with one function per flag
- Rollout plan documented per flag
- Observability: variation logged on every check
- Cleanup tickets filed for every release flag
- Weekly report of flags older than N days