Feature-Flag Graduation Review¶
Governance procedure — instantiates Variation Consolidation and Feature Selection
A release-governance review that converts a trial feature into a standard, rollback, or removal decision.
Feature-Flag Graduation Review is a release-governance checkpoint that decides whether a feature currently living behind a flag is ready to graduate to on-by-default, stay behind the flag for now, or be removed — governing the safe flip, not re-judging the feature's merits. Its defining move is to treat the flag as a reversible switch and gate graduation on operational readiness: compatibility with the rest of the system and a formal sign-off from the people who own the affected surfaces. Promotion becomes a controlled, undoable release event rather than a one-way door. It takes the "is this feature worth keeping?" verdict as an input and asks the narrower, engineering question: given that verdict, is it safe and approved to flip this on for everyone?
Example¶
A project-management SaaS has been running a new search-ranking algorithm behind a flag for a slice of accounts. An earlier readout already showed the new ranker improves task-find rate, so the merits are settled. The graduation review governs the flip. It checks compatibility: does the new ranker break the saved-search API, the mobile client, or interact badly with the enterprise-permissions flag? It confirms the rollback path: if error rates spike after graduation, can the flag flip the change off instantly, without a redeploy? And it requires acceptance: the SRE lead, the security reviewer, and the product owner each sign off. Only when all three gates are green does the flag flip to default-on for all accounts — and it stays wired for a quarter so a regression can be reverted in seconds. A feature that fails the compatibility check is held behind the flag until fixed; a feature the readout showed no value in has its flag removed and its dead code deleted.
How it works¶
- Take the merits verdict as input. The review does not re-derive whether the feature is worth keeping — it governs readiness for release, starting from an evidence verdict supplied upstream.
- Verify compatibility. The feature must not break dependent systems, clients, or other flags when it goes to 100% — the check that a trial passing at 5% traffic often hides.
- Confirm the rollback path. The flag must be able to switch the change off (or reactivate a removed one) immediately, so promotion carries no irreversibility risk.
- Require sign-off, then schedule cleanup. Named owners across the affected functions approve the flip; the graduated or removed flag is put on a cleanup schedule so it doesn't linger.
Tuning parameters¶
- Readiness bar — how many gates must be green to graduate. A higher bar is safer but slows every promotion.
- Rollback retention window — how long the flag stays wired after graduation. Longer keeps reversibility but leaves conditional code paths in production.
- Sign-off breadth — which functions must approve (SRE, security, support, legal). Broader catches more cross-cutting risk but adds latency and veto points.
- Graduation cohort — flip for everyone at once, or ramp through a canary. A ramp bounds blast radius; an instant flip is simpler but riskier.
- Flag-cleanup SLA — how quickly graduated or removed flags are deleted from the code. Tight SLAs prevent flag debt but cost engineering time.
When it helps, and when it misleads¶
Its strength is that it makes promotion safe, reversible, and accountable: a feature goes to default-on only when it can't break its neighbors and can be pulled back in seconds, with named owners on record. That is what lets an organization graduate variants briskly without betting stability on each one.
Its characteristic failure is feature-flag debt — flags that graduate but are never cleaned up, so the codebase silently accumulates dead switches and permanent conditional complexity that outlives the decisions that created them.[n1] Two more shadow it. Sign-off decays into a rubber stamp, a gate that everyone approves reflexively until it protects nothing. And the review is easily mistaken for the merits decision: a feature that passes every readiness gate looks "good" even when its actual value was never established — ready is not the same as worth it. The discipline is to enforce a flag-cleanup SLA, keep sign-off substantive, and require an explicit merits verdict as a precondition so readiness can never quietly stand in for value.
How it implements the components¶
Feature-Flag Graduation Review fills the release-governance slice of the archetype — the machinery that makes promoting a variant a safe, approved, reversible act:
rollback_or_reactivation_option— the flag is the reversible switch; graduation keeps it wired so the change can be flipped off (or a removed feature reactivated) without a redeploy.compatibility_constraint— the review verifies the feature is compatible with dependent systems, clients, and other flags before it goes to full traffic.stakeholder_acceptance_gate— graduation requires formal sign-off from the named owners of every affected surface, a binding go / no-go rather than an informal nod.
It governs the safe flip but does not judge the feature's merits: it does not set the retain / adapt / retire rule or record the learning behind it — selective_retention_rule, lineage_and_rationale_log — that's Post-Pilot After-Action Review; nor measure the experiment that established the feature's value — performance_evidence_capture — that's A/B Test Readout.
Related¶
- Instantiates: Variation Consolidation and Feature Selection — this review is how a flagged variant is safely and reversibly promoted, held, or removed.
- Consumes: A/B Test Readout supplies the merits verdict — the evidence that the flagged feature is worth graduating in the first place.
- Sibling mechanisms: A/B Test Readout · Post-Pilot After-Action Review · Best-Practice Harvesting Workshop · Model Feature Selection Protocol · Merge and Deprecation Plan · Multi-Criteria Selection Rubric · Champion–Challenger Evaluation
Editorial Notes¶
Form Classification¶
Form family: Decision, Gate & Allocation
Rationale: Feature-Flag Graduation Review operates as a case-specific gate, selection, routing, prioritization, or resource disposition because it a release-governance review that converts a trial feature into a standard, rollback, or removal decision.
Independent corroboration: The frozen evidence defines Feature-Flag Graduation Review as 'A release-governance review that converts a trial feature into a standard, rollback, or removal decision', so its operative form is Decision, Gate & Allocation.
Nearest alternative: Assessment, Review & Assurance — Compatibility and rollback readiness are reviewed, but standardize, rollback, or remove is the release gate's bounded disposition.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Specialized
Rationale: Retiring or graduating runtime flags is a software release-engineering lifecycle practice.
Related originating lineages:
- Organizational & Management Science — Formal portfolio-review and governance gates shape the review ceremony and recorded decision.
Review resolution: Both reviewers agree that computer_science is primary. I retain organizational_management only as formative origin lineage(s), without treating every later application as an origin. cross_disciplinary_synthesis is appropriate because the exact artifact combines contributions from multiple professional lineages. Reach is specialized as a separate applicability judgment: it does not widen or narrow the recorded provenance. Encyclopedia synthesis is true because the exact generalized artifact is an encyclopedia-authored combination or refinement. The secondary differences are reconciled with no unresolved primary-provenance ambiguity.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; medium confidence.
Notes¶
The nearest twin is Post-Pilot After-Action Review, and the line between them is worth holding: this review governs the safe flip of a still-live software feature — reversible flag, compatibility check, sign-off — whereas the after-action review makes the merits retain / adapt / retire decision and records the learning behind it for a completed field pilot. Keeping "ready to ship" separate from "worth shipping" is the whole point of the split.
[n1] Feature-flag debt — the accumulation of stale flags that were promoted or abandoned but never removed, leaving conditional branches and dead code that raise maintenance cost and testing complexity. It is the flag-management analogue of technical debt, and the standard mitigation is a lifecycle policy that requires each flag to be cleaned up within a fixed window after its decision. ↩