Dead Switches, Hidden Debt: Engineering Feature Flags That Age Out on Schedule

Feature flags look like switches. In practice, they are contracts between a product decision and the codebase that must honor it. A flag is created to change behavior, rolled out to a subset of users, and eventually retired. When the retirement step is skipped, the switch remains, but the decision behind it has expired. The code still branches, the tests still multiply, and new engineers still ask why.

CodeOrigin's first-principles approach is useful here: define the lifecycle before building the tooling. A flag without an owner and a deadline is not a feature flag. It is an unidentified conditional.

The Lifecycle Is the Contract

Every flag should carry four pieces of information: what behavior it controls, who owns the decision, when it should be removed, and what condition justifies removal. Those details are not administrative overhead. They are the minimum context required for another engineer to act safely.

A useful lifecycle has five stages:

1. Proposal: the flag is named, scoped, and assigned an owner.
2. Rollout: the flag is enabled for a cohort and monitored.
3. Decision: the team chooses full rollout or rollback.
4. Cleanup: the winning branch is made permanent and the flag is removed.
5. Verification: tests and documentation no longer reference the flag.

Most organizations invest heavily in stages two and three. Stages four and five are where debt accumulates. The flag stays because removal feels risky, because the owner changed teams, or because no one remembers whether the off state still matters.

Why Stale Flags Become Debt

A stale flag is not merely untidy. It changes the economics of the codebase. Each flag roughly doubles the number of theoretical code paths, even if only one path is active in production. Test matrices grow, incident response slows, and security review becomes ambiguous: which branch is actually reachable?

Stale flags also distort ownership. When a flag outlives its decision, the person who understands it may have left the project. The team inherits a conditional that cannot be confidently removed. That is technical debt in its clearest form: a future cost created by present ambiguity.

The fix is not a heroic cleanup sprint. The fix is a small system that makes expiry visible before it becomes mysterious.

A Minimal Expiry Model

Start with a machine-readable registry. A single file in the repository is enough for many teams:

flags:
  - key: checkout_v2
    owner: payments-platform
    created: 2026-08-14
    expires: 2026-11-30
    issue: PAY-1842
    description: Route eligible US customers to the new checkout flow.

The fields matter more than the format. owner must be a team or an accountable engineer, not a distribution list. expires must be a real date, not a quarter or a vague milestone. issue gives reviewers a place to ask questions. The registry becomes the source of truth for both humans and automation.

A simple policy keeps the model honest: every new flag must have an owner and an expiry date no more than 90 days out. Extensions are allowed, but they require a new date and a short reason in the pull request. The point is not to punish long-lived flags. The point is to force a deliberate decision each time a flag survives.

Wiring Expiry Into CI

Visibility without enforcement is easy to ignore. Add a lightweight check to continuous integration that fails when a flag is overdue or missing required metadata. The check can be a short script:

from datetime import date
import yaml

with open('flags.yaml') as handle:
    registry = yaml.safe_load(handle)

today = date(2026, 11, 9)
problems = []

for flag in registry['flags']:
    if not flag.get('owner'):
        problems.append(f"{flag['key']}: missing owner")
    if not flag.get('expires'):
        problems.append(f"{flag['key']}: missing expiry")
    elif flag['expires'] < today:
        problems.append(f"{flag['key']}: expired on {flag['expires']}")

if problems:
    raise SystemExit('\n'.join(problems))

The date should normally come from the runtime clock rather than a constant; the example uses the current review date for clarity. The script can run on every pull request or as a scheduled job. For a gentler rollout, start with warnings in CI and a weekly report to flag owners. Once the registry is accurate, make overdue flags a failing check.

The CI check should not block unrelated work forever. A common exception path is a short-lived override file with an owner, a justification, and a hard review date. That keeps the system humane without making exceptions invisible.

Making Cleanup Repeatable

Expiry enforcement is only half the workflow. The other half is removal. Give each flag a cleanup definition before rollout: which branch becomes permanent, which tests should be deleted, which dashboards should be retired, and which documentation should change. When the flag reaches its deadline, the owner opens a cleanup pull request using that definition.

Teams can make this routine by reviewing the flag registry in the same cadence as dependency updates or incident follow-ups. A monthly fifteen-minute review is usually enough. The goal is not to remove every flag on the exact expiry date. The goal is to ensure no flag disappears from accountability.

From First Principles to Working Code

The first principle is simple: a feature flag is a temporary decision with an owner and an end date. The working code is a registry, a CI check, and a cleanup workflow that treats removal as part of delivery. Teams that adopt this model do not eliminate flags. They prevent flags from becoming invisible architecture. That distinction is the difference between controlled experimentation and hidden debt.