add-feature-flag

Add a feature flag

A flag decouples deploy from release: code ships dark, is switched on deliberately, and can be switched off in seconds. Every flag is also a branch in the code that someone must test and later delete. Add it so both paths are correct, the default is safe, and its removal is already planned.

Steps

1. Classify the flag (Pete Hodgson, "Feature Toggles"); the category sets its lifetime and how dynamic it must be:
   • release — hides unfinished or unreleased work; lives days to weeks; usually a static per-deploy value. The common case.
   • ops / kill switch — lets operators turn off a costly or risky path under load; may live long; must be changeable at runtime without a deploy.
   • experiment — A/B cohorts; decided per request/user; needs consistent bucketing.
   • permission — per-user or per-plan access; long-lived; this is product logic, so treat it as an entitlement, not a temporary flag.
2. Use the repo's flag mechanism. A flags-service SDK, a config-driven module, env vars, a settings table. Call search_lore for naming and where flags are declared. If there is none, propose the smallest one (a typed config module with defaults, see the add-config-option skill) via request_decision before building infrastructure.
3. Name, type and default it. A descriptive, namespaced name (checkout.new-address-form), boolean unless variants are required. Never reuse a retired flag's name: old code still reading it will wake up. The default is the SAFE state — the current behaviour — and it is also what the code does when the flag source is unreachable or the value is malformed.
4. Declare once; decide at one point. Register the flag with owner, purpose, category and removal date. Evaluate it at the edge of the feature (the route, the component, the job entry) through one router function, and pass the decision (or the chosen implementation) inward. Scattered isEnabled() calls deep in the call stack make both testing and removal a hunt.
5. Keep both paths correct. Old and new paths must never share half-migrated state: if the new path writes a new data shape, the old path must still read it, or the rollout needs an expand/contract migration (the add-db-migration skill). A flag may ADD a security check; it must never switch one off.
6. Test the combinations that ship. Run the affected tests with the flag OFF (today's production) and ON (the intended release), plus an explicit test that an unset or unreadable flag yields the default. You do not need every combination of every flag — test the configurations you will actually run.
7. Make the decision observable. Record the flag state where behaviour diverges (a structured log field or metric label) so an incident can be tied to a rollout; never log user data alongside it.
8. Plan the removal now. The removal date in the declaration, a note in the evidence, and a follow-up the human can file. A flag that has been 100% on for weeks is dead code; the deprecate-and-remove skill retires it (delete the flag, the losing path and its tests together).