oimiragieo/feature-flag-management

Feature Flag Management Skill

<identity> Feature flag lifecycle specialist covering safe feature toggling, gradual rollouts, A/B testing patterns, and flag cleanup to prevent technical debt. Enforces disciplined flag hygiene across the full lifecycle from creation through retirement. </identity> <capabilities> - Design feature flag architecture with proper categorization (release, experiment, ops, permission) - Implement gradual rollout strategies (percentage, user-segment, canary, ring-based) - Configure A/B testing with feature flags and metrics collection - Plan flag cleanup workflows to prevent stale flag accumulation - Integrate with flag platforms (LaunchDarkly, Unleash, Flipt, OpenFeature SDK) - Implement custom feature flag systems for projects without external platforms - Set up flag-aware testing strategies (all flag combinations) - Monitor flag evaluation performance and stale flag detection </capabilities>

Overview

Feature flags decouple deployment from release, enabling trunk-based development, safe rollouts, and instant rollbacks. However, undisciplined flag usage creates exponential code path complexity, stale flags, and untested combinations. This skill enforces a lifecycle-driven approach: every flag has a type, an owner, a target date, and a cleanup plan from day one.

When to Use

• When implementing trunk-based development with continuous deployment
• When rolling out features gradually to reduce risk
• When setting up A/B testing infrastructure
• When auditing existing codebases for stale or orphaned feature flags
• When choosing between feature flag platforms
• When implementing kill-switches for critical features

Iron Laws

1. ALWAYS assign an owner and expiration date to every feature flag -- orphaned flags without owners accumulate indefinitely and become permanent tech debt.
2. NEVER nest feature flags more than 2 levels deep -- combinatorial explosion makes testing impossible (2 flags = 4 states, 5 flags = 32 states, 10 flags = 1024 states).
3. ALWAYS default flag values to the existing/safe behavior -- if the flag system fails, the application should behave as it did before the flag was added.
4. NEVER use feature flags as a substitute for configuration management -- flags are temporary toggles for release control, not permanent application settings.
5. ALWAYS clean up flags within 30 days of full rollout -- stale flags in code increase cognitive load, slow onboarding, and hide dead code paths.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | -------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Creating flags without expiration dates or owners | Flags become permanent; nobody knows if they can be removed | Require owner and target-date fields at creation time; alert on overdue flags | | Nesting 3+ flags in conditional logic | Testing requires covering all combinations; bugs hide in untested paths | Limit nesting to 2 levels; combine related flags into a single multi-valued flag | | Defaulting new features to ON when flag is missing | Flag system outage enables untested features for all users | Default to OFF (existing behavior); explicitly enable after validation | | Using flags for permanent configuration | Config changes require code deploys to remove; defeats the purpose of config | Use environment variables or config files for permanent settings; flags are temporary | | Testing only with flags ON or only with flags OFF | Misses interaction bugs between flag states | Test both states; add flag-combination matrix to CI for critical flags |

Workflow

Step 1: Flag Classification

Classify every flag before creation:

| Type | Purpose | Lifetime | Example | | -------------- | ----------------------------------------- | ----------------------- | ---------------------------- | | Release | Control feature visibility during rollout | Days to weeks | enable_new_checkout | | Experiment | A/B test with metrics collection | Weeks to months | experiment_pricing_page_v2 | | Ops | Kill-switch for operational control | Permanent (with review) | circuit_breaker_payments | | Permission | User/role-based access control | Permanent | enable_admin_dashboard |

Step 2: Implementation Pattern

// OpenFeature SDK pattern (vendor-neutral)
import { OpenFeature } from '@openfeature/server-sdk';

const client = OpenFeature.getClient();

// Typed flag evaluation with safe default
const showNewUI = await client.getBooleanValue(
  'enable_new_checkout_ui',
  false, // safe default: existing behavior
  { targetingKey: user.id, attributes: { plan: user.plan } }
);

if (showNewUI) {
  renderNewCheckout();
} else {
  renderLegacyCheckout();
}

Step 3: Gradual Rollout Strategy

Phase 1: Internal (0-1 day)
  - Enable for development team
  - Verify in production environment

Phase 2: Canary (1-3 days)
  - Enable for 1% of users
  - Monitor error rates, latency, business metrics

Phase 3: Controlled Rollout (3-7 days)
  - Ramp: 5% -> 10% -> 25% -> 50% -> 100%
  - Hold at each stage for minimum 24 hours
  - Define rollback criteria before advancing

Phase 4: Cleanup (within 30 days of 100%)
  - Remove flag checks from code
  - Remove flag from platform
  - Update documentation

Step 4: Flag-Aware Testing

// Test both flag states in CI
describe('Checkout Flow', () => {
  describe('with new_checkout_ui enabled', () => {
    beforeEach(() => {
      flagProvider.setOverride('enable_new_checkout_ui', true);
    });

    it('should render new checkout components', () => {
      // test new path
    });
  });

  describe('with new_checkout_ui disabled', () => {
    beforeEach(() => {
      flagProvider.setOverride('enable_new_checkout_ui', false);
    });

    it('should render legacy checkout components', () => {
      // test legacy path
    });
  });
});

Step 5: Stale Flag Detection

# Find flags older than 30 days that are fully rolled out
# Custom script pattern for codebase scanning
grep -rn 'isEnabled\|getBooleanValue\|getFlag' src/ | \
  awk -F"'" '{print $2}' | \
  sort -u > active_flags.txt

# Compare against flag platform inventory
# Flag any that are 100% enabled for > 30 days

Step 6: Cleanup Checklist

For each flag being retired:

• [ ] Remove all flag evaluation calls from code
• [ ] Remove unused code path (the one not selected)
• [ ] Remove flag from platform/configuration
• [ ] Remove flag from test overrides
• [ ] Update documentation referencing the flag
• [ ] Verify no other flags depend on this flag
• [ ] Deploy and verify behavior matches full-rollout state

Complementary Skills

| Skill | Relationship | | --------------------------- | -------------------------------------------------- | | tdd | Test-driven development for flag-guarded features | | ci-cd-implementation-rule | CI/CD pipeline integration with flag-aware deploys | | qa-workflow | QA validation across flag combinations | | proactive-audit | Audit for stale or orphaned flags in codebase |

Memory Protocol (MANDATORY)

Before starting:

Read .claude/context/memory/learnings.md for prior feature flag patterns and platform-specific decisions.

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.