Stale feature flag audit

Use this procedure to assess whether a feature flag can be retired safely based on concrete evidence. An old flag or one with low recent activity is not proof of staleness. Keep production behavior unchanged during the audit; do not edit live configuration or remotely toggle flags.

Triggers

• A user or maintenance task requests auditing, retiring, or cleaning up a suspected stale or fully rolled-out feature flag.
• A feature rollout has reached 100% stable deployment or an experiment has concluded, and flag retirement is scheduled.
• A codebase audit identifies obsolete gating or conditional branching tied to legacy feature toggles.

Non-triggers

• The flag is an operational kill switch, emergency rollback control, permanent circuit breaker, or tenant-specific runtime safeguard (preserve these safeguards).
• The request involves modifying, synchronizing, deleting, or remotely toggling live configurations or flag services (live systems are strictly read-only).
• Deleting flags based solely on age, an empty query window, or lack of recent commits without end-to-end reference tracing.
• Performance optimization or functional redesign of the feature itself.

Process

1. Establish scope and read-only inspection. Identify the repository, relevant service(s), target flag, runtime environments, commit snapshot, and proposed outcome (retain, remove, or investigate). Inspect project instructions and flag-management conventions first. Redact credentials and sensitive configuration values.
2. Trace the flag end to end. Search the exact key and likely variants, then follow references across the full stack:
   • Definitions, defaults, aliases, renamed keys, compatibility maps, generated constants, and dynamically assembled names (prefixes, suffixes, tenant/platform/environment keys).
   • Wrappers, helper functions, SDK/client abstractions, middleware, decorators, dependency injection, and configuration loaders that read, transform, cache, or override the value. Trace callers and call sites in both directions.
   • All consumers across services, packages, jobs, migrations, APIs, clients, deployment manifests, dashboards, scripts, tests, and documentation. Check cross-service producers/consumers and shared contracts; inspect schema and tool/API definitions where flags affect exposed behavior.
3. Map flag-to-flag dependencies. Identify nested gates, prerequisites, mutually exclusive or ordered flags, rollout cohorts, and fallback selection. Construct a dependency map; do not treat each key in isolation.
4. Verify configuration read-only. When authorized read access is available, inspect the effective configuration for each relevant environment, including remote flag service state, deployment overrides, SDK cache/default behavior, and local/tenant overrides. Prefer documented read-only commands, queries, or UI views; avoid commands that apply, sync, or toggle state.
   • Do not change, delete, publish, synchronize, or remotely toggle live configuration.
   • Record what was observed, when, for which environment/tenant, and what access was unavailable. A repository default, test fixture, or one environment's value does not establish global inactivity.
   • If live configuration cannot be checked, state so explicitly and treat runtime inactivity as unverified. Do not infer that a flag is dead from low usage, an expired rollout, or an empty sample alone.
5. Assess retirement evidence and preserve safeguards. Classify each relevant reference as active behavior, compatibility/alias path, operational control, test-only, documentation-only, or unresolved. Consider whether the flag is still needed for rollback, migrations, older clients, staged deployments, compliance, or incident response.
   • A removal recommendation requires evidence that all consumers and aliases are understood, dependent flags and fallback paths remain valid, effective configuration is known or its uncertainty is explicitly accepted by the owner, and tests cover both relevant branches and the post-removal behavior.
   • Preserve kill switches, SDK fallbacks, local overrides, and operational safeguards unless an authorized owner explicitly approves their retirement. If evidence conflicts or is incomplete, recommend retaining the flag.
6. Propose a minimal change. Prepare a focused, small, reviewable diff or draft PR plan. Separate codebase cleanup from any live-configuration action; live config remains untouched in this audit. Route proposed changes through human review before merging.

Evidence and Reporting

Provide a structured report containing:

• Finding: Retain, remove, or investigate, with calibrated confidence and decision boundaries.
• Evidence: Traced definition-to-consumer paths, aliases, wrappers, dynamic lookups, cross-service references, dependency map, and read-only live configuration observations (or stated gaps). Distinguish verified facts from hypotheses.
• Impact and Uncertainty: Affected services and environments, behavior changes, uninspected paths, and operational or rollback risks.
• Proposed Diff: Exact files, keys, and minimal code diff or draft PR plan removing obsolete branching while retaining defaults and safeguards.

Verification

• Run targeted tests covering both previously toggled branches and the post-removal behavior.
• Execute static analysis, type checks, and build validation across all supported configurations.
• Verify that test coverage and platform matrix support are preserved.
• Document exact validation commands and results; state clearly which checks were run and which could not be run.
• Define a clear rollback plan specifying how to restore prior behavior if unexpected issues emerge.

Example

Trigger: A maintenance task requests auditing and removing feature flag enable_circuit_breaker_fallback because it has been active for over 12 months with no recent code modifications.

Investigation & Evidence:

• Traced flag references across service definitions, client SDKs, and configuration schemas.
• Found flag defined in config/flags.yaml with explicit metadata type: operational_kill_switch and permanent: true, serving as a safety circuit breaker during external payment gateway outages.
• Verified live configuration read-only: effective value is true across staging and production environments. Live configurations remain untouched.

Finding & Safety Gate:

• The flag is an operational kill switch and permanent safeguard, not a temporary rollout flag.
• Retirement is rejected; operational safeguards must be preserved.

Report & Next Step:

• Report findings confirming the flag's critical role as an operational safeguard, cite the read-only configuration verification, and route to the service owner for retention confirmation rather than proposing code deletion.