Pipeline & Operations · master area
Flag Lifecycle
Create → wire → test → enable → stabilise → clean up. Cleanup is the step most teams skip — and the step that turns "the feature flag system" into "a graveyard of dead branches in living code."
Owners: PO, Tech Lead, Developer Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: Technical debt is unresolved decisions in the chain.
Where it lives in the chain
- How We Build · Feature Flags · lifecycle — the canon
The six steps
- Create — flag defined in source control. Name (
grading.shortcut-submit), default (false), owner, removal date. If the removal date is missing, the flag is not created. - Wire — both paths (on, off) implemented and tested. Untested off-path is rollback theatre.
- Test — pipeline runs both paths. Unit, integration, visual.
- Enable — staged rollout per Feature Flag Platform. 1% → 5% → 25% → 100%.
- Stabilise — flag stays on for the named soak window (often 2 weeks). Signal reading happens here.
- Clean up — flag removed from code; off-path deleted; flag-platform entry retired; PR linked to the original PR that created the flag.
What good practice looks like
The team has a flag inventory — visible to the PO at portfolio review. Each entry: flag name, created date, removal date, current state. Flags past their removal date are escalated. A flag that has lived past its removal date is technical debt with interest accruing.
Cleanup is scheduled at flag-creation time, not negotiated later. "This flag is enabled at the release. Cleanup is the first story of cycle N+1." The story is in the backlog before the flag is in production.
A team that skips cleanup ends up with code that branches in five places for flags nobody flips. Every developer who reads the code wonders which path is live; the answer requires reading the platform UI; the platform's authority drifts from the code. The chain-aware label is adr-drift: the ADR said the flag would be removed at release+2 weeks; the code drifted from the decision.
Related crafts
- Feature Flag Implementation — the code half
- Feature Flag Platform — the runtime half