HIVE80lab — Ops notes

Feature flag cleanup checklist

Every flag has an owner and a kill date — or it becomes the outage you shipped in advance.

A feature flag starts as safety and decays into debt. Each one is a second code path that only compiles in your head: a branch nobody reads, a config value nobody dares touch, an “off” state nobody has tested since the quarter it shipped. The flag you forget is not neutral — it is unvisited risk with a name like checkout_v2_final_REAL, and it will be involved in an incident you could have deleted instead. This page is the cleanup discipline: an inventory, three fields per flag, a removal ritual, and a monthly sweep that fits in fifteen minutes.

1. Inventory first — and three classes, not one pile

You cannot clean up what you have not listed. One sweep produces the inventory: grep the codebase for flag reads, scan config and feature-flag dashboards, and union the results into a single list. Then split it into three classes, because they have different lifetimes:

A flag missing from the inventory is the dangerous one — not because it is worse, but because nobody counts it, and uncounted risk is the kind that compounds.

2. The three-field rule: owner, kill date, removal task

Every flag in the inventory carries three fields, and a flag missing any one of them is a defect:

Code review enforces this cheaply: a PR that adds a flag without an owner and a kill date gets one comment — “add the three fields” — and does not merge until they exist. Thirty seconds at merge time deletes an hour of archaeology later.

3. The removal ritual (and the off-path drill)

Removal is the step everyone skips, which is how codebases end up carrying 120 flags. The ritual:

4. The monthly 15-minute sweep: OWN or KILL, no third state

Once a month, fifteen minutes, hard stop. Print the flags older than 90 days whose owner, date, or ticket field has gone stale, and give each one a verdict:

The sweep is deliberately cheap. Fifteen minutes monthly beats a quarterly “flag debt week” that gets cancelled twice and then never scheduled again.

5. What flags must never gate

Some things are not flag material, no matter how convenient it looks:

6. Worked example

A 40-person SaaS, checkout team. The flag inventory said 120 flags; 38 had no owner, 61 had no kill date, and the median age was 14 months. The motivating incident: a release flag that had gone default-on a year earlier, whose off-path broke silently in a library upgrade — when a slow memory leak made someone try the switch, it did nothing, and checkout ran with doubled latency for nine days before anyone found the flag. One cleanup sprint: 46 flags killed (24 of them dead code paths verified by grep), 11 converted to owned kill-switches with off-path drills, 63 flags total, median age 30 days. Six weeks later a bad deploy hit the same checkout path; the kill-switch flipped in 4 minutes, and the incident report was one page, not one post-mortem.

7. Metrics

Where this fits

Flags sit at the intersection of three siblings: the change freeze window policy decides when flag changes pause entirely; the maintenance window announcement is where slow-rollback removals belong; the runaway automation runbook is what your kill-switches exist for. For the rest of the estate — the flags, the crons, the access nobody remembers granting — book the small-team ops audit & runbook service.

From the HIVE80lab kit

Related: the change freeze window policy pauses flag changes along with everything else, the maintenance window announcement schedules the downtime slow removals need, and the runaway automation runbook is what your kill-switches are for.