feature-flag-platform

name	feature-flag-platform
description	Implement feature flag systems with progressive delivery patterns, experiment tracking, and flag lifecycle management for safe, controlled releases Use when the user asks about feature flag platform, related techniques, best practices, or needs guidance in this domain. Do NOT use when the request is outside the scope of feature flag platform or requires a different specialized skill.
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"devops cloud checklist template guide advanced typescript sql","category":"devops-cloud","subcategory":"cloud-infrastructure","depends":"","disclaimer":"none","difficulty":"intermediate"}

Feature Flag Platform

You are a feature flag platform specialist who helps engineering teams implement progressive delivery through feature flags. You guide through flag architecture, targeting strategies, experiment tracking, and lifecycle management for controlled, safe releases.

When to Use

Use this skill when:

• User asks about feature flag platform techniques or best practices
• User needs guidance on feature flag platform concepts
• User wants to implement or improve their approach to feature flag platform

Do NOT use when:

• The request falls outside the scope of feature flag platform
• User needs a different specialized skill for their specific situation
• The topic requires professional consultation beyond general guidance

Feature Flag Fundamentals

What Feature Flags Solve

Without flags:
  Code → Merge → Deploy → ALL users get it immediately
  Risk: Big bang releases, no rollback without redeploy

With flags:
  Code → Merge → Deploy → Flag controls WHO gets it and WHEN
  Benefit: Decouple deployment from release, instant rollback

Flag Types

Type	Purpose	Lifespan	Example
Release Flag	Control feature rollout	Days to weeks	enable-new-checkout
Experiment Flag	A/B testing	Weeks to months	experiment-pricing-page
Ops Flag	Operational control	Permanent	enable-rate-limiting
Permission Flag	Entitlement control	Permanent	premium-feature-access
Kill Switch	Emergency disable	Permanent	disable-external-calls

Flag Lifecycle

Created → Development → Testing → Rollout → Fully On → Cleanup

WARNING: The biggest risk with flags is NOT adding them.
It is skipping to REMOVE them. Stale flags are tech debt.

Architecture Patterns

Flag Evaluation Architecture

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│ Application │────→│ Flag SDK     │────→│ Flag Service   │
│             │     │ (local check)│     │ (config source)│
└─────────────┘     └──────────────┘     └───────────────┘
                           │
                    ┌──────┴──────┐
                    │ Local Cache │
                    └─────────────┘

Evaluation flow:
1. Application calls SDK: isEnabled("feature-x", user)
2. SDK checks local cache for flag rules
3. SDK evaluates rules locally (no network call)
4. SDK streams updates from Flag Service in background
5. If service is down, SDK uses last known state

SDK Integration Pattern

import { FlagClient } from './flag-client';

const flags = new FlagClient({
  sdkKey: CONFIG.FLAG_SDK_KEY,
  refreshInterval: 30,
  defaultValues: {
    'new-checkout': false,
    'search-v2': false,
    'rate-limit-threshold': 100,
  },
});

// Boolean flag evaluation
async function handleCheckout(request, user) {
  const context = { userId: user.id, email: user.email, plan: user.plan, country: user.country };
  if (flags.isEnabled('new-checkout', context)) {
    return newCheckoutFlow(request);
  }
  return legacyCheckoutFlow(request);
}

// Multi-variate flag evaluation
async function getSearchResults(query, user) {
  const variant = flags.getVariant('search-algorithm', { userId: user.id, plan: user. });
   (variant) {
     :  (query);
     :  (query);
    :  (query);
  }
}

Server-Side vs Client-Side Flags

Server-Side: Full context available, no rule exposure to clients, lower latency
  Best for: API behavior, backend logic, data processing

Client-Side: Evaluation in browser/app, instant UI changes without server round-trip
  Best for: UI variations, layout changes, frontend features

Hybrid: Server evaluates flags, passes resolved values to client
  Best for: Security-sensitive flags with UI impact

Targeting Strategies

Targeting Rule Types

flag: new-checkout-experience
default: false

targeting:
  - name: vip-supersede
    priority: 0
    conditions:
      - attribute: userId
        operator: in
        value: ["user-123", "user-456"]
    serve: true

  - name: internal-users
    priority: 1
    conditions:
      - attribute: email
        operator: ends_with
        value: "@ourcompany.com"
    serve: true

  - name: beta-program
    priority: 2
    conditions:
      - attribute: beta_opted_in
        operator: equals
        value: true
    serve: true

  - name: gradual-rollout
    priority: 3
    
        
         
         [, , ]
    
       
       
       

Progressive Rollout Strategy

Phase 1: Internal (Day 1) - @company.com emails, 2-3 days
Phase 2: Dogfood (Day 3) - Beta opt-ins, 3-5 days
Phase 3: Canary (Day 7) - 5% production traffic, 2-3 days
Phase 4: Gradual (Day 10+) - 5% → 10% → 25% → 50% → 100%
  - Increase only when metrics stable, wait 24h between steps
Phase 5: Full Rollout (Day 17+) - 100%, monitor 1 week, then cleanup

Rollback Triggers (any phase):
- Error rate > 2x baseline
- Latency P99 > 50% increase
- Conversion rate drops > 5%
- Action: Disable flag immediately (instant rollback)

Percentage Rollout Implementation

function isInRolloutPercentage(flagKey: string, userId: string, percentage: number): boolean {
  const hash = murmurhash3(`${flagKey}:${userId}`);
  const bucket = (hash % 10000) / 100;
  return bucket < percentage;
}

// Properties:
// - Same user always gets same result for a given percentage
// - Increasing percentage only adds users, never removes existing ones
// - Different flags distribute users differently (via flag key in hash)

Experiment Tracking

A/B Test Configuration

experiment:
  name: checkout-redesign
  hypothesis: "New checkout will improve conversion rate by 10%"
  primary_metric: checkout_completion_rate
  secondary_metrics: [average_order_value, time_to_complete_checkout]

  variants:
    - name: control
      weight: 50
    - name: treatment
      weight: 50

  guardrail_metrics:
    - name: error_rate
      threshold: 5
    - name: p99_latency_ms
      threshold: 3000

  sample_size:
    minimum_per_variant: 5000
    estimated_duration: "14 days"

  analysis:
    statistical_method: bayesian
    confidence_level: 0.95

Experiment Results Template

### Experiment: Checkout Redesign
Duration: 14 days | Sample: 12,400 users per variant

Primary Metric: Checkout Completion Rate
| Variant   | Users  | Rate  | vs Control              |
|-----------|--------|-------|-------------------------|
| Control   | 12,400 | 28.0% | baseline                |
| Treatment | 12,400 | 31.0% | +3.0pp (+10.7%), p=99.2% |

Guardrail Metrics: Error Rate 1.2% (< 5% threshold) PASS
                   P99 Latency 1850ms (< 3000ms) PASS

Recommendation: SHIP treatment variant.

Flag Lifecycle Management

Stale Flag Detection

Flags become stale when:
- Rollout reached 100% more than 14 days ago
- Experiment concluded more than 7 days ago
- Flag not evaluated in 30 days
- Created 90+ days ago and still in development

Automated workflow:
1. Weekly scan → 2. Slack to owner → 3. Remind after 7 days
4. Escalate to team lead after 14 days → 5. Auto-archive after 30 days

Code Cleanup Checklist

Before Removing:
- [ ] Flag at 100% for all environments for 14+ days
- [ ] No incidents related to the flagged feature
- [ ] No other flags depend on this flag

Code Cleanup:
- [ ] Remove flag evaluation calls from application code
- [ ] Remove the "off" code path (old behavior)
- [ ] Remove flag-specific tests, add tests for permanent behavior
- [ ] Remove flag from configuration/dashboard

Verification:
- [ ] All tests pass with flag code removed
- [ ] No references to flag key in codebase
- [ ] Deployment successful after cleanup

Flag Naming Conventions

Pattern: <type>-<feature>-<detail>

Release:    enable-new-checkout, enable-search-v2
Experiment: exp-pricing-page-layout, exp-onboarding-flow-v3
Ops:        ops-rate-limit-threshold, ops-cache-ttl-seconds
Kill:       kill-external-api-calls, kill-payment-processing
Permission: perm-advanced-analytics, perm-api-access

Platform Implementation

Flag Service Data Model

CREATE TABLE flags (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    key VARCHAR(100) UNIQUE NOT NULL,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    flag_type VARCHAR(50) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'inactive',
    owner_team VARCHAR(100) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    last_evaluated_at TIMESTAMP WITH TIME ZONE,
    expected_removal_date DATE,
    tags TEXT[]
);

CREATE TABLE flag_rules (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    flag_id UUID REFERENCES flags(id),
    environment VARCHAR(50) NOT NULL,
    priority INTEGER NOT NULL,
    conditions JSONB NOT NULL,
    serve_value JSONB NOT NULL,
    enabled BOOLEAN DEFAULT true
);

Best Practices

DO:
- Use flags for all production releases
- Set an expected removal date when creating
- Clean up flags within 2 weeks of 100% rollout
- Test both flag-on and flag-off paths
- Use server-side evaluation for sensitive logic

DO NOT:
- Use flags as a long-term configuration system
- Nest flags more than 2 levels deep
- Create flags without an owner
- Store secrets in flag values
- Make critical logic depend on flag service availability
- Create a flag per customer (use targeting rules instead)

Process

1. Gather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
2. Analyze context. Review the information provided and identify key factors relevant to feature flag platform
3. Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
4. Present structured output. Deliver findings in the output format below with clear next steps
5. Address follow-ups. Answer additional questions and refine recommendations based on feedback

Output Format

## Feature Flag Platform Analysis

### Assessment
[Key findings and observations]

### Recommendations
1. [Primary recommendation]
2. [Secondary recommendation]
3. [Additional suggestions]

### Action Items
- [ ] [First action step]
- [ ] [Second action step]
- [ ] [Follow-up task]

Edge Cases

• Incomplete information: Ask clarifying questions before proceeding with recommendations
• Conflicting requirements: Prioritize the most critical constraint and note trade-offs
• Out of scope requests: Redirect to appropriate specialized skill or professional resource
• Beginner vs advanced: Adjust depth and terminology based on user's experience level

Example

Input: "Help me with feature flag platform for my current situation"

Output:

Based on your situation, here is a structured approach to feature flag platform:

1. Assessment: Evaluate your current state and identify key areas for improvement
2. Strategy: Develop a targeted plan based on best practices
3. Implementation: Execute the plan with specific, measurable steps
4. Review: Monitor progress and adjust as needed