Feature Flag Cleanup Checker

Introduction

Feature flag cleanup is the lifecycle work that removes temporary release gates after the feature, experiment, or rollback path no longer needs them. A flag that stays in place after rollout can keep dead branches in application code, increase test combinations, hide owner gaps, and make later incidents harder to reason about.

The useful cleanup question is not just whether a flag exists. A good review checks age, expiry date, rollout state, recent usage, code references, dependencies, owner assignment, and whether the flag is temporary or permanent. A release flag at 100% rollout with no recent checks and no code references is very different from a kill switch that still protects production behavior.

Cleanup results should be treated as triage. They help a team decide which flags need code removal, dependency work, owner review, archive checks, or continued monitoring, but they do not replace production validation or a platform-specific archive workflow.

Technical Details:

Temporary feature flags usually become cleanup candidates when three signals line up: the rollout has reached a final state, the flag is old enough or past its cleanup date, and traffic or code evidence suggests the flag is no longer needed for active behavior. Permanent operational controls need a different review path because kill switches, permission guards, entitlement checks, and circuit breakers can remain useful after a release is stable.

The checker models those two paths separately. It normalizes rows from headered CSV or legacy column order, then evaluates each flag against the selected policy thresholds. Recognized fields include flag key, owner, created date, expiry date, lifecycle status, flag type, rollout percentage, last seen date, recent check count, code-reference count, dependency count, environments, and notes.

Recent usage can be shown by a nonzero check count or a recent last-seen date. Code references matter because archiving a flag while application code still evaluates it can leave the application on fallback behavior. Dependencies matter because parent or child flags can make cleanup unsafe until rollout relationships are removed or confirmed.

Decision priority is intentionally conservative. Dependency blockers outrank ordinary cleanup because parent or child flag links can make removal unsafe. An expired flag with partial rollout becomes a rollout-state problem before it becomes an archive candidate. A flag with zero code references can move toward archive only when usage, age, status, or expiry evidence also supports cleanup.

The health score is a trend indicator for similar reviews, not an automatic approval score. A small inventory with one high-priority blocker can score worse than a large inventory with several routine review rows, so the cleanup queue and evidence columns should drive the actual work order.

Everyday Use & Decision Guide:

Start with a review label that matches the service, product area, sprint, or release train. That label appears in the snapshot and exports, so a specific value such as checkout quarterly flag review is more useful than a generic team name.

Use Quarterly cleanup for a normal hygiene sweep, Release hygiene when completed launch work should be checked monthly, and Strict launch gate when cleanup should happen before a release train closes. The advanced thresholds should match the feature-flag platform or team standard you use for stale age, recent usage, and expiry grace.

• Paste a CSV export with headers when possible. Header aliases are normalized, so common names such as flag, owner, created, expires, rollout, last used, checks, and code references can still parse.
• Use the legacy column order only for quick copied rows: flag, owner, created, expires, status, type, rollout, last seen, checks, code references, dependencies, environments, and notes.
• Leave Include permanent review signals on when permanent controls still need owner and note checks.
• Leave Raise missing owners on for release reviews where an owner gap should become priority work.
• Use Ledger row limit to keep the visible tables compact. The JSON output still keeps the normalized flag list.

The safest reading path is summary, then Cleanup Snapshot, then Cleanup Queue. The summary shows the queued count, archive-ready count, remove-code count, blocker count, and health badge. The snapshot explains the policy thresholds and aggregate evidence. The queue gives the first work items with priority, decision, action, and evidence.

Parsing and scoring run in the browser page against the pasted or loaded text. The checker does not fetch a feature-flag platform, scan a repository, or validate production traffic by itself. Treat copied CSV, downloaded JSON, exported DOCX tables, and chart images as release records because they can contain flag keys, owners, environments, and notes.

Step-by-Step Guide:

Review one inventory snapshot at a time so the queue, chart, and exports describe the same reference date and policy.

1. Enter Review label with the service, sprint, or product area that should appear in exported evidence.
2. Select Cleanup policy. Adjust stale age, usage window, and expiry grace in Advanced only when your team uses different thresholds.
3. Set Reference date. Use the current date for a live review or a release date for a planned cleanup gate.
4. Paste the inventory, drop a CSV or TXT file on the source field, use Browse CSV, or load one of the sample inventories.
5. If parser notes appear, fix missing headers, skipped rows, or unexpected column order before relying on the queue.
6. Read the badges in the summary, then open Cleanup Snapshot for aggregate evidence and Flag Review Ledger for every visible parsed flag.
7. Open Cleanup Queue and handle blocked rows before remove-code rows, then archive candidates, then owner or lifecycle review rows.
8. Use Flag Debt Mix Chart to show why the queue exists by reason category, or use JSON when a workflow needs normalized evidence.

Finish by checking the first few queue rows against the source platform before archiving anything. If the platform still shows recent evaluations, code references, or dependencies that were not in the pasted source, update the inventory and rerun the review.

Interpreting Results:

The primary number is the cleanup queue size. A queued flag has at least one action path beyond ordinary monitoring or already archived status. The queue includes archive candidates, remove-code rows, owner reviews, missing cleanup dates, permanent reviews, rollout-state problems, and dependency blockers.

Dependency block and Resolve rollout state should slow the review down. They mean the available evidence points to cleanup pressure, but something makes immediate archive or code removal unsafe. Remove code means application references still need cleanup before platform archiving. Archive candidate is the closest output to archive-ready, but it still needs a platform check and fallback confirmation.

The chart groups reasons by archive-ready, remove-code, review, and blocked work. It is useful for a cleanup summary because it shows whether the queue is dominated by old completed flags, missing owners, dependency blockers, or code-reference work.

Worked Examples:

Completed release flag with code still present

A flag created 100 days ago has status launched, rollout 100, recent checks, and three code references. Under quarterly cleanup, the age and uniform rollout make it cleanup-relevant, but code references keep it in Remove code rather than archive. The next action is a cleanup pull request, followed by a fresh reference check.

Inactive flag with no owner and no code references

A flag with status inactive, zero checks, no code references, and no owner can become an Archive candidate or Owner review depending on the other evidence and priority order. If ownership is required for archive approval, assign the owner before closing the platform record.

Expired partial rollout

A release flag at 40% rollout with an expiry date past the grace period becomes Resolve rollout state. The evidence says the cleanup date has passed, but the partial rollout means the team needs to finish rollout, disable the flag, or extend the date before deleting code.

Permanent kill switch in an old service

A permanent kill switch can be old and still correct. With permanent review enabled, an old control with weak notes or missing ownership moves to Permanent review, not stale temporary cleanup. The right check is whether the control still has a named owner, tested fallback behavior, and a clear operational purpose.

FAQ:

Glossary:

Feature flag

A runtime control that changes behavior without requiring a new deployment.

Temporary flag

A release, experiment, or migration flag that should usually be removed after the final state is reached.

Permanent flag

A long-lived operational, permission, entitlement, or kill-switch control that may remain after release cleanup.

Code reference

Evidence that application code still reads or branches on the flag key.

Dependency block

A parent, child, or prerequisite relationship that should be resolved before a flag is archived.

Usage window

The number of days used to decide whether last-seen or check-count evidence still looks recent.

References:

• Reducing technical debt from feature flags, LaunchDarkly documentation.
• Archiving flags, LaunchDarkly documentation.
• Manage stale flags, Harness Developer Hub.
• Piranha: Reducing Feature Flag Debt at Uber, ICSE SEIP paper.