Feature flags are product memory

A feature flag is a decision that has not settled yet.

It says the team wants a way back, needs a staged rollout, or is still comparing paths. That makes flags a kind of product memory. Memory becomes debt when nobody can explain why it exists.

Names should describe the uncertainty rather than the color of the switch:

dashboard_query_cache_rollout
billing_proration_policy_2024
agent_file_write_approval_required
search_reranker_experiment

The record around the flag matters as much as the key:

type FeatureFlagRecord = {
  key: string
  owner: string
  createdAt: string
  reason: string
  expectedRemoval?: string
  defaultState: boolean
  rollbackMeaning: string
  affectedSurfaces: string[]
}

Turning a flag off is only rollback if the old path still works. A database migration, new API shape, or changed user state can make the flag forward-only while the switch still looks reversible. Every flag should answer what happens if it flips now.

Ownership starts after launch. Someone needs to remove the branch, delete dead tests, update analytics, close the rollout note, or explicitly document why the flag remains. The useful questions are:

• who owns it?
• is it rollout, experiment, permission, pricing, or migration?
• what breaks when its state changes?
• what is the removal plan?

AI flags make rollback harder. A new model route may already have generated content, stored embeddings, changed memory, or triggered tools. The record should say what the flag can undo:

{
  "key": "support_answer_gpt56_route",
  "kind": "model-route",
  "baseline": "support_answer_sonnet5_route",
  "evalSuite": "support-policy-regression",
  "rollbackMeaning": "new requests return to baseline; existing drafts remain visible",
  "watch": ["refund_policy_slice", "citation_missing_rate", "p95_latency"]
}

A flag is not complete at 100 percent rollout. The old path should be removed or deliberately retained, tests should stop covering dead branches, and dashboards should stop splitting traffic on a switch that no longer moves.

Flags are useful because they remember uncertainty. They stay useful when somebody retires the memory after the decision lands.