Feature Flag Ops

Feature Flag Operations

Feature flags decouple deployment from release. Deploy code any time. Release features when ready. Roll back without redeploying.

Flag Lifecycle

CREATE → TEST → RAMP → FULL ROLLOUT → CLEANUP

Every flag should go through this lifecycle. Flags that skip CLEANUP become permanent tech debt.

1. Create

FLAG NAME: enable_new_checkout
TYPE: release (temporary) / operational (permanent) / experiment (A/B test)
DEFAULT: false (OFF)
OWNER: [who's responsible for this flag]
CLEANUP DATE: [date to remove the flag - set it NOW]

2. Test

• Verify: feature works with flag ON
• Verify: existing behavior works with flag OFF
• Both paths are tested in CI

3. Ramp (Progressive Rollout)

Day 1: 1% of users (canary - catch crashes)
Day 2: 5% of users (small sample - check metrics)
Day 3: 25% of users (moderate - verify at scale)
Day 5: 50% of users (large - final validation)
Day 7: 100% of users (full rollout)

At each stage:

• Monitor error rate (should not increase)
• Monitor latency (should not degrade)
• Monitor business metrics (should not drop)
• Check support tickets (no new complaints)

4. Full Rollout

Flag is ON for 100% of users. Feature is fully released.

5. Cleanup (Critical - Don't Skip)

1. Remove the flag check from code (always return the "ON" path)
2. Remove the "OFF" code path entirely
3. Delete the flag from your flag management system
4. Merge cleanup PR

Set a cleanup date at creation time. If the flag is still alive 30 days after full rollout, it's tech debt.

Flag Types

| Type | Lifetime | Example | Cleanup | |------|----------|---------|---------| | Release flag | Days to weeks | New checkout flow | Remove after full rollout | | Operational flag | Permanent | Maintenance mode, rate limit bypass | Keep (but review annually) | | Experiment flag | Weeks | A/B test: button color | Remove after experiment concludes | | Permission flag | Permanent | Premium features, beta access | Keep (tied to entitlements) |

Most flags should be release flags. If you have > 10 permanent flags, audit them.

Kill Switch

Every feature behind a flag has an instant rollback mechanism.

INCIDENT: New checkout causing payment failures
ACTION: Toggle enable_new_checkout → OFF
EFFECT: All users immediately get old checkout
TIME:  threshold (flag sprawl) |
| Flag age | Alert if release flag > 30 days old (stale) |
| Flag without owner | Alert (orphaned flag) |
| Error rate per flag variant | Alert if ON variant has higher errors |
| Rollout percentage changes | Audit log (who changed what, when) |

## Flag Hygiene

### Monthly Flag Review

For each active flag:

• Is it still needed?

→ Release flag at 100%? CLEAN UP → Experiment concluded? CLEAN UP → Operational flag? Review if still relevant

• Does it have an owner?

→ No owner? Assign one or clean up

• Is it tested?

→ Both ON and OFF paths covered in tests?

### Maximum Active Flags
Set a team limit (e.g., max 15 active flags). When you hit the limit, clean up before creating new ones. This prevents flag sprawl.

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|-------------|---------|-----|
| Flags never cleaned up | Code full of dead branches, combinatorial complexity | Set cleanup dates, enforce in reviews |
| Nested/dependent flags | Untestable combinations | One flag per feature, no nesting |
| Flag as permanent config | Bypasses proper config management | Use config for config, flags for rollout |
| No monitoring per variant | Can't tell if new path is broken | Monitor metrics split by flag variant |
| Manual percentage decisions | Inconsistent, risky | Follow standard ramp schedule |
| Testing only ON path | OFF path breaks, rollback fails | Test both paths in CI |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pvnarp](https://github.com/pvnarp)
- **Source:** [pvnarp/agent-skills](https://github.com/pvnarp/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.