What counts as a stale feature flag, and which flags should never be removed?

A flag is stale when all four of these hold:

  • One value for everyone. It has served the same value to all traffic, in every environment, for a period your team agreed on in advance. Agreeing up front keeps the decision from being argued flag by flag.
  • Nothing in flight. No experiment is still collecting data and no rollout is paused partway.
  • No objection from the owner. The owning team has confirmed it, or nobody has claimed the flag after a stated notice period.
  • Not a permanent switch. It was never meant to be long-lived.

The last criterion matters most. "Unchanged for six months" describes a finished release and a healthy kill switch equally well. Age alone cannot tell you which one you are looking at, so the flag's type has to.

Toggle types and their expected lifespan

Toggle type Purpose Meant to be temporary? Action when unchanged
Release Hide incomplete or risky code during rollout Yes, days to weeks Remove
Experiment Split traffic to compare variants Yes, until the result is decided Remove after the decision
Ops / kill switch Shed load or disable a dependency during incidents No Keep and reclassify
Permission / entitlement Gate features by plan, role or tenant No Keep and reclassify

When not to clean up

An ops toggle that hasn't flipped in a year is unused only because nothing has failed yet. If you delete it, you lose the one fast lever you had during the next outage.

Entitlement checks also look static, but they encode business rules. Removing one can quietly give paid features to every customer.

Neither type should be deleted. Move them out of the flag system into named, documented configuration with an owner. That stops them from showing up in staleness reports and makes their permanence explicit.

Why is removing a flag from a monolith a production change?

Every flag that outlives its rollout leaves a branch in the code. Two independent boolean flags produce four possible paths through a function, and five produce thirty-two. Nobody tests all of them, so the paths that run in production and the paths covered by CI slowly drift apart. Reviewers have to work out which branch is live before they can judge a change. New engineers spend time understanding code that has not executed in months. That is the real cost of feature toggle debt: every change in the affected code takes longer to make and to verify.

Removing the flag deserves the same care as any other production change, because a monolith concentrates risk:

  • One flag, many owners. A flag added for a checkout change may also be read in billing, notifications, and an admin report, each owned by a different team. Deleting it changes behavior in all of those modules at once.
  • Shared deploys. The removal ships in the same artifact as everyone else's changes. If something breaks, rolling back also reverts unrelated work, and it is harder to identify the flag removal as the cause.
  • Silent defaults. If you delete the flag's entry from the flag store while code still evaluates it, most SDKs fall back to the default value in code. They do not raise an error. If that default is false for a flag that has been true for a year, you have turned the feature off without anyone noticing.

Backend and platform engineers should own the cleanup, because they control the flag store and the build. Each module owner signs off on the removal in their area before it merges.

When should you run a flag cleanup?

Use this process whenever a temporary flag has finished its job. In practice that means one of these triggers:

  • A release flag has reached 100% and stayed there for the observation window your team agreed on, with no rollbacks in that time.
  • An experiment has a decision. The winning variant is chosen and nobody needs the losing variant's data anymore.
  • A flag has passed its review date in the registry, and the owner confirms it is done.
  • You are about to change code that contains the flag. Removing the flag first means the new change is written and reviewed against one path, not two.
  • An inventory shows mismatches, such as keys in code with no store entry, which are already silently serving defaults.

Hold off when the flag is a kill switch or entitlement check, when a rollout is paused or partial, when per-tenant overrides are still active, or when the evaluation data does not yet cover a full business cycle. Also avoid starting removals during a release freeze or right before a high-traffic period, when a revert would be costly. Wait for a normal deploy window.

How does the cleanup process work end to end?

The process has four phases. Each phase produces evidence that the next one depends on.

  1. Classify. Confirm the flag's type and owner. Only release and experiment flags go forward. Ops and permission flags are reclassified as configuration.
  2. Prove it is dead. Join the flag store export, code references and runtime evaluation data on the flag key. Then check overrides and targeting rules. A flag goes forward only when all three sources agree it serves one value.
  3. Remove in stages. First hardcode the winning value, then delete the losing branch and its dead code and tests, then delete the flag definition. Deploy and observe after each stage.
  4. Prevent recurrence. Register new flags with an owner, a type and a review date, and let CI warn on overdue flags and then fail on them.

The sections below cover each phase in that order, and the checklist at the end condenses it into tickable items.

How do you build a flag inventory and prove a flag is dead?

Start with three lists and join them on the flag key: every flag defined in the flag store, every key referenced in the codebase, and every key that appears in runtime evaluation data. Each mismatch tells you something. A flag defined in the store but missing from code may still be read by another service that shares the store. A key found in code but missing from the store means something is silently falling back to a default. A flag that is evaluated at runtime but cannot be found in code points to a reference your search missed.

Look past literal string matches

Plain grep finds quoted keys. AST-based search finds calls to the flag client even when the key is passed through a variable. Neither tool catches everything. Search separately for:

  • keys built at runtime, such as "checkout_" + region
  • keys referenced in templates, SQL, migration scripts and stored procedures
  • scheduled jobs and batch workers that ship outside the main deploy
  • YAML or environment config files that map flags to behavior
  • other services or repositories that read the same store

Collect enough evidence

A flag is dead only when all of the following hold:

  • Evaluation logs show no meaningful variation across a full business cycle, including month-end and quarterly jobs.
  • No per-environment or per-tenant overrides remain.
  • No targeting rules still split traffic.

Sampled evaluation data and short log retention can make a rarely used flag look dead. Waiting through a longer observation window lowers that risk, but it slows cleanup. Choose the window based on what breaks if you are wrong.

import csv
import json
import sys

def load_store(path):
    with open(path) as f:
        return {flag["key"] for flag in json.load(f)}

def load_lines(path):
    with open(path) as f:
        return {line.strip() for line in f if line.strip()}

def load_evaluated(path):
    with open(path, newline="") as f:
        return {row["flag_key"] for row in csv.DictReader(f)}

store = load_store(sys.argv[1])
code = load_lines(sys.argv[2])
evaluated = load_evaluated(sys.argv[3])

report = {
    # Candidates only: another service sharing the store may still read these.
    "in_store_not_in_code": store - code,
    # Code silently falls back to a default because the flag is missing.
    "in_code_not_in_store": code - store,
    # Something evaluates these but the search missed it (dynamic keys, other repos).
    "evaluated_not_in_code": evaluated - code,
    # Strongest removal candidates; still verify overrides and targeting rules.
    "store_only_never_evaluated": store - code - evaluated,
}

for name, keys in report.items():
    print(f"{name} ({len(keys)}):")
    for key in sorted(keys):
        print(f"  {key}")

A stdlib-only Python script that joins the flag store export, grep-derived code references and runtime evaluation data on the flag key and prints each category of mismatch for follow-up.

How does staged flag removal work?

Removal works best as three small changes, each deployed and observed before the next. Every stage alters one thing, so if something breaks, you know which change caused it and can revert that change alone.

Stage 1: Collapse to the winning constant

Make the flag's evaluation return the winning value without consulting the flag system. If calls go through a single wrapper, change it there. Before, isNewCheckoutEnabled(user) called the flag client and returned its result. After, it returns true and makes no client call. Every call site keeps its branches, but only the winning path runs. Deploy this change and watch error rates and the business metrics the flag affected. Reverting is a one-line change and puts the old evaluation back.

Stage 2: Delete the losing branch

Remove the else paths and the helpers, queries, and templates that only those paths reached. This diff is often the largest of the three. Stage 1 has already proven the losing paths are not needed in production, so this diff should not change behavior.

Stage 3: Remove the definition

Once a search finds nothing that reads the flag, including scripts, config files, and other services, delete the wrapper and the flag's definition in the flag system. If you delete the definition first, any caller you missed silently gets the default value.

For trivial flags, such as a single boolean check with no helpers, you can combine all three stages into one change. That saves two deploys. The cost is a revert that restores everything together, which makes it harder to tell which part caused a problem.

// Shape of the flag client the wrapper used before Stage 1.
interface FlagClient {
  isEnabled(flagKey: string, context: { userId: string }): boolean;
}

interface User {
  id: string;
}

// BEFORE (Stage 0): the wrapper asks the flag system on every call.
export function isNewCheckoutEnabledBefore(flags: FlagClient, user: User): boolean {
  return flags.isEnabled("new-checkout", { userId: user.id });
}

// AFTER (Stage 1): the wrapper returns the winning value.
// It no longer calls the flag system. The signature stays the same,
// so no call site has to change in this deploy.
// To revert, restore the single return line above.
export function isNewCheckoutEnabled(_user: User): boolean {
  // Stage 2 deletes the else branches at call sites.
  // Stage 3 deletes this wrapper and the flag definition.
  return true;
}

// Call site, unchanged in Stage 1. Only the first branch can run now.
// Stage 2 removes renderLegacyCheckout and anything only it uses.
export function renderCheckout(user: User): string {
  if (isNewCheckoutEnabled(user)) {
    return renderNewCheckout(user);
  }
  return renderLegacyCheckout(user);
}

function renderNewCheckout(user: User): string {
  return `new checkout for ${user.id}`;
}

function renderLegacyCheckout(user: User): string {
  return `legacy checkout for ${user.id}`;
}

Stage 1 of the removal changes only the wrapper so it returns the winning constant and stops calling the flag client, which leaves every call site and the losing branch in place for Stage 2 and keeps the revert to one line.

How do you remove dead code and tests after collapsing a flag?

Collapsing the conditional is the start of the cleanup. Follow the losing branch outward: the methods it called, any classes only those methods used, configuration keys, metrics emitted only on that path, alerts and dashboards built on those metrics, and runbooks or docs that describe the old behavior. A dashboard panel that silently flatlines is harmless until someone reads it during an incident and draws the wrong conclusion.

Compiler and linter warnings about unused symbols are useful hints, but they are not proof. A method can look unused and still be reached through reflection, a dependency injection container that wires beans by name, a serialization framework, a scheduled job registered in configuration, or dynamic dispatch in a dynamically typed module. Coverage data has the same limit, because it only shows what your tests exercised. Before deleting a symbol, search for its name as a string as well as an identifier. Check framework configuration files too.

Tests need sorting, not bulk deletion:

  • Delete tests that only exercise the dead branch.
  • Simplify tests that set up both states but assert on surviving behavior. Remove the flag setup and keep the assertions.
  • Look for shared fixtures, test base classes, or environment defaults that force the flag on or off. These can hide in setup code far from the test that relies on them.

A lower test count is expected. Lower coverage of the surviving path is a regression, so compare coverage for those files before and after the change.

Leave irreversible changes such as dropping columns or tables for a separate change with its own explicit review. Unlike code, a dropped column cannot be restored by a revert.

#!/usr/bin/env bash
set -euo pipefail

SYMBOLS=(
  "checkout_v2_pricing"            # flag key
  "LegacyPriceCalculator"          # class only the old branch used
  "computeLegacyDiscount"          # method called only from the old branch
  "pricing_legacy_fallback_total"  # metric emitted only on the old path
)

OPS_DIR="${OPS_DIR:-../ops-config}"
SEARCH_DIRS=(.)
[ -d "$OPS_DIR" ] && SEARCH_DIRS+=("$OPS_DIR")

for sym in "${SYMBOLS[@]}"; do
  echo "== $sym"
  # -F: fixed string, so string literals match too (reflection, DI bean names,
  #     serializer config, scheduled jobs registered in YAML/XML).
  # -i: case-insensitive, so a bean named legacyPriceCalculator also matches.
  grep -rniF --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=build \
    -- "$sym" "${SEARCH_DIRS[@]}" || echo "   no matches"
done

echo "== test code that still sets the flag"
grep -rnE --exclude-dir=.git -- 'checkout_v2_pricing.*(true|false|on|off)' \
  src/test tests .env.test 2>/dev/null || echo "   none found"

A shell sweep that searches code, config, tests and a separate ops repo for leftover flag, class, method and metric names as plain strings. This catches references that unused-symbol warnings miss, such as reflection, dependency injection by name and dashboard queries.

What are the alternatives to manual flag cleanup, and how do you prevent toggle debt?

Teams rarely rely on a single approach. Most combine two or three of the following.

Approach How it works Main weakness
One-off purge A dedicated effort removes many flags at once Large, risky batches, and debt starts accumulating again immediately afterwards
Owner-driven cleanup The flag's creator removes it after rollout Stalls when owners change teams
Scheduled report A periodic list of old or unevaluated flags goes to owners Easy to ignore
CI lint on expiry Build fails when a flag passes its removal date Encourages extending dates without review
Ticket automation A removal ticket is opened at flag creation or expiry Adds backlog noise
Reclassify as configuration Long-lived switches become documented, permanent settings Can hide abandoned flags

The cheapest prevention happens at flag creation. Require an owner, a type (release, experiment, ops, permission), and a removal or review date. Keep a visible list of open flags so stale ones are noticed in normal planning, not during an incident.

Enforcement has trade-offs. Hard CI failures get attention, but under deadline pressure engineers may push dates forward without checking anything. Reminders are low-friction, which is also why people ignore them. A practical middle ground is to warn first and fail only after a grace period, and to require a reviewer for each extension.

Illustrative estimate: assume a team creates 4 flags a month. Removing a fresh flag takes about 1 hour. Removing a year-old flag takes about 4 hours, because surrounding code has changed and context is gone. Budgeted cleanup then costs roughly 4 hours a month. A yearly purge of 48 flags costs roughly 192 hours.

Automated detection produces false positives, such as flags evaluated only in rare paths. It also produces false negatives, such as flag keys built dynamically from strings. Owner judgment is still required before any removal.

import json
import sys
from datetime import date, timedelta

GRACE = timedelta(days=14)  # warn first, fail only after the grace period
TYPES = {"release", "experiment", "ops", "permission"}

def main(path):
    with open(path) as fh:
        flags = json.load(fh)
    today = date.today()
    errors = warnings = 0
    for f in flags:
        name = f.get("name", "<unnamed>")
        # Lifecycle starts at creation: every flag needs an owner, a type and a date.
        missing = [k for k in ("owner", "type", "review_by") if not f.get(k)]
        if missing or f["type"] not in TYPES:
            print(f"ERROR {name}: missing {missing} or invalid type")
            errors += 1
            continue
        due = date.fromisoformat(f["review_by"])
        if today > due + GRACE:
            # Extending the date should go through a reviewed PR, not a silent edit.
            print(f"ERROR {name}: past {due} + grace; remove it or extend with reviewer sign-off (owner: {f['owner']})")
            errors += 1
        elif today > due:
            print(f"WARN  {name}: overdue since {due}; CI fails after {due + GRACE} (owner: {f['owner']})")
            warnings += 1
    # The summary doubles as the visible list of open flags for planning.
    print(f"{len(flags)} open flags, {warnings} warnings, {errors} errors")
    return 1 if errors else 0

if __name__ == "__main__":
    sys.exit(main(sys.argv[1] if len(sys.argv) > 1 else "flags.json"))

A standard-library Python CI check that requires an owner, type and review date for every flag, warns when a flag is overdue, and fails the build only after a grace period so extensions get a deliberate, reviewed change.

How does flag cleanup save engineering time?

The savings come from removing work that stale flags add to every change near them, and from doing the removal while it is still cheap.

  • Fewer paths to reason about. Each removed boolean flag halves the number of possible paths through the code that reads it. Authors and reviewers no longer have to work out which branch is live before judging a change.
  • Smaller, faster tests. Tests that set up both flag states, plus fixtures that force a flag on or off, go away. The remaining tests cover the path that actually runs in production, so a CI failure points at a real problem more often.
  • Faster onboarding. New engineers stop reading and asking about code that has not executed in months.
  • Shorter incident triage. Without dead branches, misleading dashboard panels and outdated runbooks, responders spend less time ruling out code that cannot be running.
  • Cheaper removals. Removing a flag soon after rollout, while the author still has context and the surrounding code has barely changed, takes less effort than removing it a year later. The illustrative estimate above, with its assumed inputs, shows how that difference compounds when cleanup is deferred to a yearly purge.
  • Less review overhead per removal. The staged approach keeps each diff small and single-purpose, so reviews are quick and reverts do not require untangling unrelated work.
  • Automation does the tracking. The inventory join, the pre-deletion sweep and the CI lint replace manual audits. Engineers spend their time on the judgment calls automation cannot make.

Copyable pre-removal and post-removal checklist

Owner judgment, applied through a fixed checklist, catches what automated detection misses. Copy this into the cleanup ticket and tick each item.

Before removal

  • Owner sign-off recorded. The team that owns the behavior confirms the flag is done. Whoever wrote the flag may not know who now depends on it.
  • Flag type confirmed. Release and experiment flags are candidates. Kill switches and permission flags are not, even if they have not changed in months.
  • Evaluation data reviewed over a full business cycle. Monthly billing runs, quarter-end jobs and annual renewals evaluate flags that a one-week window never sees.
  • Overrides and targeting checked. A flag that is 100% on globally but has a per-tenant override is serving two behaviors, so collapsing it changes production for that tenant.
  • Indirect references searched. Look for dynamically built keys, config files, scripts, SQL, templates and other repositories that read the same key.

After removal

  • Collapse deployed and observed. The code hardcodes the winning value and runs in production before anything else is deleted.
  • Dead branch removed in an isolated diff. Do not mix it with renames, reformatting or unrelated refactors. A diff that does one thing reverts in one step, without conflicts.
  • Flag store entry deleted. Do this only after no deployed build reads the key.
  • Related config, alerts, dashboards and docs cleaned. Stale panels and runbooks keep pointing people at a flag that no longer exists.
  • Error rates and key business metrics watched after each deploy. Compare them against the previous baseline, not against zero.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to stale feature flags cleanup, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.