Feature Flag Cleanup Checker

Introduction

Feature flags move release risk from deployment time into runtime control. A team can ship code while keeping a feature hidden, expose a change to a small audience, run an experiment, protect a risky path with a kill switch, or grant access by plan or role. That flexibility works only when each flag has a clear purpose, owner, lifecycle, and retirement path.

The cleanup problem appears after the release or experiment has served its purpose. Temporary flags leave conditional branches in code, extra targeting rules in the flag platform, fallback behavior that may no longer be tested, and names that future engineers must interpret. A flag catalog can look healthy because nothing is broken today while still carrying old decisions that slow reviews, incident response, and future rollouts.

Age is only one cleanup clue. A 20-day release flag that is fully rolled out, unused, and no longer referenced in code may be closer to archive than a three-year-old kill switch that still protects a payment path. Purpose matters because release flags, experiment flags, operational controls, permission flags, and permanent entitlement guards have different expected lifetimes and different failure modes.

The safest cleanup review ends with specific next actions instead of a blanket delete list. Flags with active dependencies, partial rollout, missing owners, unknown usage, or remaining code references need follow-up before archive. Flags that are fully rolled out, unused, without code references, and without dependency blockers can usually move to platform verification and archive, but the final change should still be confirmed against the live environments that served the flag.

How to Use This Tool:

Start with a feature-flag inventory export, then tune the review window to match the cleanup policy your team uses. Headered CSV gives the checker the clearest owner, lifecycle, usage, code-reference, and dependency evidence.

1. Enter a Review label for the product area, service, sprint, or cleanup sweep. The label appears in the exported handoff evidence.
2. Choose Cleanup policy. Quarterly cleanup uses a 90-day stale age, Release hygiene uses 60 days, and Strict launch gate uses 30 days with a shorter usage window.
3. Set the Reference date. Created-date age, expiry grace, and last-seen usage checks are measured against this date.
4. Paste a Feature flag inventory, drop a CSV or TXT file onto the field, or use one of the samples. Useful columns include key, owner, created, expires, status, type, rollout, last_seen, checks_30d, code_refs, dependencies, environments, and notes.
5. Open Advanced when your policy differs from the defaults. Adjust Stale age threshold, Recent usage window, Expiry grace period, Ledger row limit, Permanent flag review, or Owner gap priority.
6. Read Parser notes before acting on the queue. A missing header, skipped flag key, ambiguous status, missing date, or unknown usage evidence can move work into review instead of archive.
   If the checker reports no header row, add explicit CSV headers before trusting Flag health score or copying rows into tickets.
7. Use Cleanup Snapshot for the batch summary, Flag Review Ledger for per-flag evidence, Cleanup Queue for work order, and Flag Debt Mix Chart for the reason split behind the queue.

Interpreting Results:

The Cleanup Queue ranks work that deserves review. It does not prove that a flag can be deleted from every environment. Treat Dependency block and Resolve rollout state rows as stop signs, because a prerequisite flag, child flag, or partial rollout can make cleanup unsafe even when a flag is old or expired.

The Flag health score is a trend signal for the inventory you pasted. A high score can still hide risk when the export omits code references, dependency counts, last-seen activity, or owner values. Check Evidence and Next action before opening archive tickets.

• Archive candidate means the supplied row points toward platform archive after verifying rollout, dependencies, and references.
• Remove code means flag branches or references should be removed before archive.
• Owner review, Add cleanup date, and Permanent review mean the missing lifecycle decision should be fixed first.
• Monitor rollout means the flag is still active or partially rolled out, so ordinary cleanup should wait.

Technical Details:

Feature-flag debt comes from carrying conditional behavior after the reason for the condition has passed. Release and experiment flags usually have a short useful life, while kill switches, permission controls, and entitlement flags can remain valid for much longer. Cleanup rules therefore need both time evidence and purpose evidence.

The strongest cleanup signals combine final state, inactivity, and removability. A flag with a completed rollout and no recent checks still needs a code-reference check. A flag with zero code references still needs dependency review. A missing owner or missing expiry date lowers confidence because nobody can confirm the intended lifecycle.

Rule Core

Each parsed flag is assigned reason labels first. The final decision comes from the strongest reason combination, with blocked states ranked before ordinary cleanup work.

Decision order matters when a flag matches several signals. Dependency and rollout blockers outrank archive and code-removal work, while permanent-flag review is deliberately lower priority than temporary cleanup blockers.

Formula Core

The health score converts queue priority into a 0 to 100 trend score for the parsed inventory.

priorityPoints come from the decision assigned to each flag, and parsedFlags is the count of usable rows. If 12 parsed flags total 360 priority points, the average priority is 30. The score is rounded from 100 minus 33, resulting in 67. A score below 60 or any queued blockers should be treated as cleanup work, not as a release readiness grade.

Limitations and Privacy Notes:

The checker scores the inventory you provide. It does not query a feature-flag platform, scan a repository, verify production targeting, or archive anything for you.

• The pasted inventory and selected file content are parsed in your browser; the page does not submit the flag list for analysis.
• Code reference counts, last-seen dates, and dependency counts are only as current as the export you pasted.
• Permanent flag review should include owner, fallback behavior, monitoring, and a documented reason to remain long-lived.

Advanced Tips:

• Use the same Reference date for repeated reviews of one release train so age, expiry, and last-seen comparisons stay comparable.
• Choose Strict launch gate when cleanup must happen before a release exits the train; it sets a 30-day stale age, 14-day recent usage window, and 0-day expiry grace.
• Keep Permanent flag review enabled for permission, entitlement, kill-switch, and operational flags so long-lived controls still receive owner and notes checks.
• Raise Ledger row limit for handoff exports, then use Flag Review Ledger to preserve the evidence behind each queue decision.
• Compare Flag Debt Mix Chart with Cleanup Queue. A chart dominated by code references points to pull-request cleanup, while dependency blocks need platform relationship review first.
• Leave Owner gap priority on when cleanup work is assigned across teams. Ownerless flags are harder to classify safely than ordinary stale rows.

Worked Examples:

A release flag named checkout_new_summary was created on 2026-01-20, expired on 2026-04-15, reached 100 percent rollout, and still shows 3 code references. With a 2026-05-29 Reference date, the Cleanup Queue should show Remove code, because archive should wait until those references are gone.

An inactive flag named legacy_coupon has 0 recent checks, 0 code references, no dependencies, and an expiry date well beyond the grace period. The Flag Review Ledger should point toward Archive candidate, while any missing owner evidence remains worth fixing before the platform change.

An experiment flag named experiment_pricing_v2 is completed and expired but still has 2 code references and 1 dependency. That dependency should push the row into Dependency block, because removing the flag before checking the relationship may break a prerequisite or child flag.

A rollout flag named checkout_shipping_banner is 35 percent rolled out, has recent checks, and has an expiry date in the future. It should appear as Monitor rollout rather than ordinary cleanup, even though code references still exist. Finish or stop the rollout before treating it as stale work.

If a pasted export has no header row, the parser uses the legacy order shown in the help text and adds a Parser notes warning. Fix the header before trusting Flag health score or copying queue rows into a cleanup ticket.

FAQ:

Glossary:

Release flag

A temporary flag used to separate code deployment from feature rollout.

Permanent flag

A long-lived control, such as a kill switch, permission flag, or entitlement guard, that should be reviewed differently from a short-lived release flag.

Code references

Known remaining uses of the flag key in application code or configuration.

Dependency block

A cleanup blocker caused by prerequisite, parent, child, or related flag relationships.

Expiry grace period

The number of days after the expiry date before an expired flag receives stronger cleanup priority.

No recent usage

A signal from zero recent checks or a last-seen date older than the selected usage window.

Flag health score

A 0 to 100 trend score based on average queue priority across parsed flags.

References:

• Introduction, OpenFeature.
• Flag statuses and lifecycle stages, LaunchDarkly Documentation.
• Reducing technical debt from feature flags, LaunchDarkly Documentation.
• Technical debt, Unleash Documentation.
• Feature Toggles (aka Feature Flags), Pete Hodgson, 09 October 2017.