Feature Flag Management Skill
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
- ALWAYS assign an owner and expiration date to every feature flag -- orphaned flags without owners accumulate indefinitely and become permanent tech debt.
- 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).
- 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.
- NEVER use feature flags as a substitute for configuration management -- flags are temporary toggles for release control, not permanent application settings.
- 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:
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.
1---2name: feature-flag-management3description: Feature flag lifecycle management -- safe feature toggling, gradual rollouts, A/B testing patterns, flag cleanup strategies, and technical debt prevention. Covers LaunchDarkly, Unleash, OpenFeature, and custom implementations.4version: 2.0.05category: DevOps6agents: [developer, devops, qa]7tags:8 [9 feature-flags,10 rollouts,11 a-b-testing,12 toggles,13 launchdarkly,14 openfeature,15 trunk-based-development,16 ]17model: sonnet18invoked_by: both19user_invocable: true20tools: [Read, Write, Edit, Bash, Glob, Grep, WebFetch]21best_practices:22 - Define a clear lifecycle for every flag (create, enable, rollout, permanent, cleanup)23 - Use typed flag values with defaults that match the safe/existing behavior24 - Clean up flags within 30 days of full rollout to prevent technical debt25 - Never nest feature flags more than 2 levels deep26 - Always include kill-switch capability for new features behind flags27error_handling: graceful28streaming: supported29verified: true30lastVerifiedAt: '2026-03-01'31source: builtin32trust_score: 10033provenance_sha: e91a4c35aa7c28e034metadata:35 source: https://skillmd.com/skills/oimiragieo/feature-flag-management36---3738# Feature Flag Management Skill3940<identity>41Feature 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.42</identity>4344<capabilities>45- Design feature flag architecture with proper categorization (release, experiment, ops, permission)46- Implement gradual rollout strategies (percentage, user-segment, canary, ring-based)47- Configure A/B testing with feature flags and metrics collection48- Plan flag cleanup workflows to prevent stale flag accumulation49- Integrate with flag platforms (LaunchDarkly, Unleash, Flipt, OpenFeature SDK)50- Implement custom feature flag systems for projects without external platforms51- Set up flag-aware testing strategies (all flag combinations)52- Monitor flag evaluation performance and stale flag detection53</capabilities>5455## Overview5657Feature 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.5859## When to Use6061- When implementing trunk-based development with continuous deployment62- When rolling out features gradually to reduce risk63- When setting up A/B testing infrastructure64- When auditing existing codebases for stale or orphaned feature flags65- When choosing between feature flag platforms66- When implementing kill-switches for critical features6768## Iron Laws69701. **ALWAYS** assign an owner and expiration date to every feature flag -- orphaned flags without owners accumulate indefinitely and become permanent tech debt.712. **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).723. **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.734. **NEVER** use feature flags as a substitute for configuration management -- flags are temporary toggles for release control, not permanent application settings.745. **ALWAYS** clean up flags within 30 days of full rollout -- stale flags in code increase cognitive load, slow onboarding, and hide dead code paths.7576## Anti-Patterns7778| Anti-Pattern | Why It Fails | Correct Approach |79| -------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |80| 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 |81| 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 |82| 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 |83| 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 |84| 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 |8586## Workflow8788### Step 1: Flag Classification8990Classify every flag before creation:9192| Type | Purpose | Lifetime | Example |93| -------------- | ----------------------------------------- | ----------------------- | ---------------------------- |94| **Release** | Control feature visibility during rollout | Days to weeks | `enable_new_checkout` |95| **Experiment** | A/B test with metrics collection | Weeks to months | `experiment_pricing_page_v2` |96| **Ops** | Kill-switch for operational control | Permanent (with review) | `circuit_breaker_payments` |97| **Permission** | User/role-based access control | Permanent | `enable_admin_dashboard` |9899### Step 2: Implementation Pattern100101```typescript102// OpenFeature SDK pattern (vendor-neutral)103import { OpenFeature } from '@openfeature/server-sdk';104105const client = OpenFeature.getClient();106107// Typed flag evaluation with safe default108const showNewUI = await client.getBooleanValue(109 'enable_new_checkout_ui',110 false, // safe default: existing behavior111 { targetingKey: user.id, attributes: { plan: user.plan } }112);113114if (showNewUI) {115 renderNewCheckout();116} else {117 renderLegacyCheckout();118}119```120121### Step 3: Gradual Rollout Strategy122123```124Phase 1: Internal (0-1 day)125 - Enable for development team126 - Verify in production environment127128Phase 2: Canary (1-3 days)129 - Enable for 1% of users130 - Monitor error rates, latency, business metrics131132Phase 3: Controlled Rollout (3-7 days)133 - Ramp: 5% -> 10% -> 25% -> 50% -> 100%134 - Hold at each stage for minimum 24 hours135 - Define rollback criteria before advancing136137Phase 4: Cleanup (within 30 days of 100%)138 - Remove flag checks from code139 - Remove flag from platform140 - Update documentation141```142143### Step 4: Flag-Aware Testing144145```typescript146// Test both flag states in CI147describe('Checkout Flow', () => {148 describe('with new_checkout_ui enabled', () => {149 beforeEach(() => {150 flagProvider.setOverride('enable_new_checkout_ui', true);151 });152153 it('should render new checkout components', () => {154 // test new path155 });156 });157158 describe('with new_checkout_ui disabled', () => {159 beforeEach(() => {160 flagProvider.setOverride('enable_new_checkout_ui', false);161 });162163 it('should render legacy checkout components', () => {164 // test legacy path165 });166 });167});168```169170### Step 5: Stale Flag Detection171172```bash173# Find flags older than 30 days that are fully rolled out174# Custom script pattern for codebase scanning175grep -rn 'isEnabled\|getBooleanValue\|getFlag' src/ | \176 awk -F"'" '{print $2}' | \177 sort -u > active_flags.txt178179# Compare against flag platform inventory180# Flag any that are 100% enabled for > 30 days181```182183### Step 6: Cleanup Checklist184185For each flag being retired:186187- [ ] Remove all flag evaluation calls from code188- [ ] Remove unused code path (the one not selected)189- [ ] Remove flag from platform/configuration190- [ ] Remove flag from test overrides191- [ ] Update documentation referencing the flag192- [ ] Verify no other flags depend on this flag193- [ ] Deploy and verify behavior matches full-rollout state194195## Complementary Skills196197| Skill | Relationship |198| --------------------------- | -------------------------------------------------- |199| `tdd` | Test-driven development for flag-guarded features |200| `ci-cd-implementation-rule` | CI/CD pipeline integration with flag-aware deploys |201| `qa-workflow` | QA validation across flag combinations |202| `proactive-audit` | Audit for stale or orphaned flags in codebase |203204## Memory Protocol (MANDATORY)205206**Before starting:**207208Read `.claude/context/memory/learnings.md` for prior feature flag patterns and platform-specific decisions.209210**After completing:**211212- New pattern -> `.claude/context/memory/learnings.md`213- Issue found -> `.claude/context/memory/issues.md`214- Decision made -> `.claude/context/memory/decisions.md`215216> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.