The feature flag management decision record: why the lifecycle model you chose determines your flag explosion surface and your testing and rollback model failure mode

A 31-person developer tools company built a continuous integration acceleration platform — caching compiled artifacts, parallelizing test execution, and reducing CI pipeline run times for 410 paying engineering teams. Their engineering team of 17 had adopted trunk-based development 18 months earlier, committing to short-lived branches of 1 to 2 days and using feature flags as the primary mechanism for decoupling code integration from feature release. The adoption had solved the long-lived branch problem: merge conflicts dropped from an average of 3.2 per week per engineer to 0.4, integration incidents caused by divergent branches fell from 11 in the quarter before adoption to 2 in the following quarter. The team was satisfied with the model and had continued extending it — every in-progress feature, every experiment, every gradual rollout was behind a flag.

In month 18, a senior engineer who was responsible for the platform's caching layer changed the default value of a flag named cache_invalidation_v2 from false to true as part of a routine flag cleanup. The flag had been created 14 months earlier to gate a new cache invalidation algorithm during its development and testing period. The creating engineer had left 9 months earlier. The flag's comment in the codebase read: "enables the v2 cache invalidation algorithm, expected to be permanent default by Q3 of last year." The engineer changing the default read the comment, confirmed the v2 algorithm had been the team's preferred implementation for over a year, and changed the default in a 3-line PR that was approved in 4 hours. The change deployed on a Thursday afternoon. Within 90 minutes, 7 customer accounts were experiencing cache misses at 10× the normal rate, CI pipeline run times were rising rather than falling, and the on-call engineer was paging the caching team.

The incident diagnosis took 4 hours and 12 minutes. The root cause was not the v2 cache invalidation algorithm itself — it was correct and had been running for flagged accounts without issue for 14 months. The root cause was an interaction between cache_invalidation_v2 and a flag named artifact_dedup_aggressive, which had been created 7 months earlier to gate an artifact deduplication optimization. The deduplication code had been written with an implicit assumption that cache invalidation events would use the v1 algorithm's event format — a format detail that had seemed stable at the time and had not been documented as a dependency. When both flags were true, the invalidation event format mismatch caused the deduplication process to fail silently and produce stale cache entries. There were 6 additional flag interactions in the codebase that the incident response team identified in the post-mortem as presenting similar risks. None of the 7 interactions was documented. The flag registry — a CSV file in the repository that 4 engineers had committed to maintaining and 3 had actually updated — contained 62 of the 140 active flags, with ownership records for 31 of them. Of the 31 with ownership records, 11 named engineers who had left the company. Connect this failure pattern to the incident severity classification decision record: the cascade of undocumented flag interactions is a failure mode whose severity was difficult to correctly classify in the first 30 minutes of the incident because the visible symptom — elevated cache miss rates for 7 accounts — looked like a severity-3 customer impact issue, not the severity-1 data integrity risk that the stale cache entries represented for CI build correctness; the severity classification decision must account for the possibility that an observed symptom is a visible surface of a larger invisible failure, and the incident response protocol for flag-change incidents must include a rapid inventory of all flags whose state was changed in the deployment window and a query against the flag interaction map for any interactions involving the changed flags before the incident is downgraded from its initial severity assessment.

A 44-person B2B SaaS built a project management analytics platform — aggregating sprint metrics, delivery throughput, and team health indicators for 520 accounts ranging from 8-person product teams to 180-person engineering organizations. Their engineering team of 26 had been running their primary data model on PostgreSQL since the company's founding. In year 3, a growing account segment was straining query performance in ways that normalization could not address. The team designed a database migration to a partially denormalized schema for the reporting tables, targeting a 6× improvement in query latency for the affected query patterns. The migration was significant enough to warrant a feature flag rollout: new accounts would be provisioned onto the new schema path from day one, and existing accounts would be migrated in batches as the team confirmed the new path was stable.

The flag was named reporting_schema_v2. The test suite was updated to cover the new schema path: 34 new integration tests covering the query patterns the migration targeted, 12 regression tests confirming the output was identical to the v1 path for the same input, and 8 performance tests confirming the latency improvement was realized. The CI pipeline ran all new tests in the flag-enabled configuration. The existing test suite — 280 tests covering the v1 path — continued to run. The migration launched for new accounts in month 1. By month 3, 140 new accounts were on the v2 path, all experiencing the expected latency improvements. The migration was considered a success. In month 4, the team shipped a release that included 6 bug fixes across the reporting layer, a new export format, and a performance improvement to the query engine. The release CI passed. The release deployed on a Tuesday morning. By noon, the support queue contained 14 tickets from accounts reporting errors on their sprint summary report. All 14 were legacy v1-path accounts. The error was a foreign key constraint violation on a join that had been present in the v1 path since the beginning of the project and had never failed before.

The root cause was a schema change introduced in month 3 for the v2 path that had added a NOT NULL constraint to a join column in a shared table. The migration script for v2 accounts had populated the column correctly. The code for v1 accounts that wrote to that column had not been updated because, at the time of the schema change, the team's mental model was that the shared table change was a v2 concern — the v1 path was not expected to write null values to that column in normal operation. In a small subset of query patterns that involved partial sprint data — sprints that had been started but not yet completed, a condition that existed only for v1-path accounts because v2-path accounts had a different sprint state model — the v1 code path wrote a null to the newly constrained column. This query pattern had not been tested since the schema change because the test suite ran the v1-path tests against the v1 schema fixtures, and the schema fixture had not been updated to reflect the NOT NULL constraint added for the v2 migration. The v1 test suite had been running against a schema that no longer matched production for 4 months, and the divergence was invisible because the test suite passed and no monitoring was in place to detect schema drift between the test fixtures and the production schema. Connect this failure to the observability strategy decision record: the schema drift between test fixtures and production schema is the same observability problem as the gap between what an SLO measures and what production actually does — both are measurement systems that were accurate at the time they were designed and that accumulated drift as the system around them changed without triggering a signal that the measurement system had become inaccurate; the observability strategy decision must include a mechanism for detecting when the observability model has diverged from the system it is monitoring; the feature flag testing model must include a mechanism for detecting when the test fixtures for the non-default flag state have diverged from the production configuration that state runs against.

A 52-person growth-stage SaaS built a B2B procurement automation platform — purchase order workflows, vendor management, and spend analytics for 290 enterprise accounts. Their engineering team of 31 had implemented Pro-tier feature gating through a combination of feature flags and account-level permission records in their database. The model had been designed in year 2: a feature flag in the flag service determined whether the feature code was active, and a row in the account_features table determined whether a specific account had access to it. The intent was that feature flags would manage the release lifecycle of features — a flag started false, was gradually enabled for Pro accounts, and was eventually removed when the feature was fully released to all Pro accounts and the code path was stable. The database permission record was the permanent access control mechanism. Feature flags were temporary; database permissions were permanent.

Over two years, the team shipped 47 Pro features and accumulated 200 active flags. Of the 200, the team believed approximately 160 were cleanup candidates — flags for features that had been fully released to Pro accounts and whose code paths had been stable for over 6 months. The cleanup estimate came from the VP Engineering reviewing the flag registry and estimating, based on feature release dates, which flags had passed their expected retirement window. In month 23, the team ran a quarterly cleanup sprint, using a script that removed flags marked as "cleanup candidate" in the registry and disabled the flag checks in the code. The script was reviewed by two engineers and tested against a staging environment containing 45 test accounts. The cleanup ran on a Friday afternoon and removed 52 flags. By Saturday morning, 140 Pro accounts had lost access to the CSV export functionality. The support queue had 89 tickets.

The root cause was a flag named export_csv_pro_v2 that had been created 19 months earlier to gate a rewritten CSV export implementation. The rewrite had improved export speed by 4× and added support for custom column configurations. The creating engineer's intent had been to migrate all Pro accounts to the v2 export and then remove the flag, with the v1 export code deleted and the v2 code becoming the permanent path. The migration had been partially completed: 410 of 550 Pro accounts had been migrated to v2. The remaining 140 were in a migration queue that had stalled 11 months earlier when the creating engineer had been reassigned to a higher-priority infrastructure project. The flag had been in the cleanup candidate registry because its creation date placed it in the "older than 12 months" cohort that the VP Engineering had flagged for review. The 140 accounts still in the v1 state were not visible in the cleanup script's pre-flight check because the pre-flight check queried the account_features table to confirm that all accounts had the feature enabled at the database level — and all 550 Pro accounts did have the feature enabled at the database level, because the database permission model controlled access to export as a category, not to the specific implementation version. The flag was the only mechanism distinguishing which implementation version each account was using, and the flag's removal was the removal of that distinction. Connect this pattern to the runbook quality decision record: the flag cleanup pre-flight check failed for the same reason that a runbook fails when it references infrastructure that has been migrated — both are procedures that were accurate when written and that accumulated undetected drift as the system changed; the runbook's step pointed to a Datadog dashboard that had been replaced by Grafana; the cleanup script's pre-flight check queried a database permission model that had been designed to complement the flag model but that had, through an incomplete migration, become an inaccurate proxy for the flag state it was supposed to supersede; the governance structure for both runbooks and flag cleanup scripts must include a validation step that confirms the pre-flight check is querying the authoritative source for the state it needs to verify, not a derived or complementary record that was accurate at design time and may have drifted since.

Structural properties set by the feature flag management decision

Three structural properties are determined when an engineering team decides — or fails to explicitly decide — how feature flags are categorized, tested, and owned throughout their lifecycle: what the lifecycle model determines about the flag accumulation surface and the code path complexity growth rate, what the testing model determines about the state coverage gap and the divergence rate between tested and production configurations, and what the ownership model determines about the knowledge decay surface and the cleanup safety margin. None of these properties are typically analyzed at the time the feature flag tooling is adopted. The lifecycle model defaults to "flags are removed when someone gets around to it," which in practice means never, because the flag that was created last week is always more important to work on than the flag created 14 months ago whose original context everyone has forgotten. The testing model defaults to testing the target state — the state the team is developing toward — because that is the state the engineers care about and the state whose bugs are immediately visible, leaving the non-default state to accumulate divergence silently. The ownership model defaults to creator memory — the engineer who created the flag knows what it controls and will remove it when it is safe — which is accurate while the creating engineer is present and actively working on the flagged feature and which decays immediately when the engineer's attention moves to other problems and progressively as months pass and turnover occurs.

Property 1: The lifecycle model and the flag accumulation surface. The flag accumulation surface is the total number of flags currently active in the codebase, and it grows monotonically when flags are added faster than they are removed, which is the default dynamic in any codebase where flag creation is a standard practice and flag removal is an individual initiative. The flag accumulation surface determines three downstream properties: the cognitive load of every engineer who reads flagged code and must reason about multiple execution paths simultaneously; the combinatorial complexity of the testing problem as interacting flags multiply the configuration space; and the knowledge decay rate for any individual flag as the total number of flags each engineer is responsible for understanding grows faster than the team's capacity to maintain that understanding. The lifecycle model is the structural constraint that keeps the accumulation surface bounded. A lifecycle model specifies, for each flag category, a maximum lifetime before a removal review is required, a set of removal criteria that must all be satisfied before the flag can be removed, and an escalation path when a flag exceeds its maximum lifetime without satisfying the removal criteria. The maximum lifetime for a release toggle is determined by the team's expected feature cycle time — a team that ships features in 2-week increments should have a maximum release toggle lifetime of 6 weeks, giving 3 full cycles for the feature to reach full rollout before the flag is reviewed; a flag that cannot be removed after 3 cycles is not a release toggle, it is a permanent feature branch in flag form, and it should be reclassified and documented as an ops toggle or permission toggle with a corresponding ownership model. The accumulation surface monitoring is a team-level metric that should be reviewed in the same cadence as code coverage and test suite runtime: flag count by category, flag age distribution by category, flags past their expected lifetime, and flags with no identified owner. Connect this property to the developer experience measurement decision record: the flag accumulation surface is a leading indicator of developer experience degradation through the context-switch frequency channel — a codebase with 140 active flags imposes a flag-reasoning context on every engineer who modifies code in the flagged areas, because every code path change must be evaluated against the set of flags that control that path's behavior; the DORA deployment frequency metric measures how often the team deploys code but cannot measure how much of each engineer's working memory is occupied by flag-conditional reasoning; the developer experience measurement system should include a flag accumulation count as a proxy metric for cognitive load growth, alongside flow state frequency and context-switch count, and should track its correlation with satisfaction and efficiency scores in the SPACE model to establish whether flag growth is a leading indicator of satisfaction decline in this team's specific context.

Property 2: The testing model and the state coverage gap. The state coverage gap is the difference between the set of flag configuration states that the test suite exercises and the set of flag configuration states that production traffic encounters. For a codebase with N active flags, the maximum possible state coverage gap is 2^N − (number of configurations tested); in practice the coverage gap is limited by the number of flags that interact — flags that control independent code paths do not combine to create new untested configurations — but identifying which flags interact requires exactly the kind of flag interaction documentation that teams typically do not maintain. The state coverage gap grows through two mechanisms: new flags are added without updating the test matrix to include the new flag configurations they introduce, and the non-default flag state diverges from the tested fixtures as the system changes around it without the non-default test coverage being updated to reflect those changes. The second mechanism — fixture divergence — is more insidious than the first because it is invisible: the test suite runs and passes, the CI pipeline is green, and the non-default state in production is quietly accumulating bugs that no test will catch until a user in the non-default state triggers them. The testing model must specify three things: the minimum test coverage requirement for each flag configuration state (at minimum: the all-default state, the all-non-default state, and any known partial states where specific accounts or environments are currently operating); the mechanism for maintaining test fixture currency when schema changes, API changes, or behavioral changes affect the non-default code path; and the process for updating the test matrix when a new flag is introduced that interacts with existing flags. The fixture currency mechanism is the most commonly omitted component: teams specify that the non-default state must be tested but do not specify how they will detect when the non-default test fixtures have drifted from the current production schema or configuration. A test that exercises the right code path against the wrong schema is not a test — it is a passing check against a synthetic environment that diverges from production over time. Connect this property to the on-call load management decision record: the state coverage gap produces incidents in the same way that alert threshold miscalibration produces on-call pages — both are failures of a monitoring system to detect a condition that it was designed to detect, and both produce incidents whose root cause is found in a decision made months earlier about what the monitoring system would and would not cover; the on-call load management ADR specifies which alert conditions are monitored and at what sensitivity; the feature flag testing ADR must specify which flag configuration states are monitored through the test suite and at what coverage depth, with an explicit enumeration of the states that are not tested and a rationale for why each untested state is acceptable to leave uncovered.

Property 3: The ownership model and the knowledge decay surface. The knowledge decay surface is the set of facts about active flags that are not retrievable from the codebase or the flag service without interrogating the creating engineer's memory. For any given flag, the knowledge decay surface includes: the population of accounts or users currently in the non-default state; the migration path from the non-default state to the default state; the timeline and status of that migration; the code paths that the flag controls beyond the primary code path visible in the flag check; and the cleanup criteria — what must be true before the flag can be safely removed. This knowledge exists in the creating engineer's head at flag creation time and decays exponentially as the engineer's context moves on. A flag created last week has near-zero knowledge decay: the creating engineer knows all of these facts and can answer questions about the flag in seconds. A flag created 18 months ago by an engineer who has since been reassigned to a different product area has high knowledge decay: the facts about the flag's current population and migration status require research to reconstruct, and some facts — why the migration stalled, which accounts were deprioritized and why — may be unrecoverable. The ownership model must address knowledge decay at three points: at creation, by requiring that the knowledge decay surface be documented explicitly in the flag registry, not just the flag's purpose; at transition, when the creating engineer's context moves away from the flagged feature, by requiring a formal handoff that transfers the facts about the flag's population and migration status to the new owner; and at cleanup, by requiring that the cleanup pre-flight check verify the flag's population directly from the authoritative production data source rather than from a derived record that may have drifted. The flag registry is the ownership model's implementation artifact — it must contain, for each active flag: the creating engineer, the current owner, the category, the expected lifetime, the population in the non-default state with the source query used to determine it, and the removal criteria. A flag registry that contains only the flag name and a one-line description is not a knowledge transfer mechanism — it is documentation for the audience who already knows the context and is useless to the on-call engineer at 2 AM who needs to understand whether the flag they are about to flip is safe to flip.

The feature flag management ADR: five sections

Section 1: Flag taxonomy and the lifecycle specification. Begin the feature flag management decision record by specifying the flag taxonomy — the set of flag categories the team uses, the definition of each category, the expected lifetime range for each category, and the governance mechanism that triggers removal when the expected lifetime is reached. The taxonomy must be exhaustive: every flag created must fit into exactly one category, and the category assignment must be made at flag creation time, not retrospectively during a cleanup sprint. A taxonomy that consists of four categories is sufficient for most engineering teams: release toggles (lifetime: 1–6 weeks, removal trigger: full rollout reached or feature cancelled), experiment toggles (lifetime: 1–4 weeks, removal trigger: experiment concluded and winner selected), ops toggles (lifetime: permanent, review trigger: quarterly review to confirm the operational need still exists), and permission toggles (lifetime: permanent for the life of the feature, ownership requirement: named owner must be current team member). The lifecycle specification defines what "done" means for a flag in each category — what conditions must all be simultaneously true before the flag can be removed. "The feature has been fully released" is not a removal criterion — it is necessary but not sufficient. The full removal criterion for a release toggle includes: the feature is at 100% rollout with no accounts in the non-default state, the non-default code path has been verified as unused for at least 7 days by production traffic monitoring, and the test matrix for the non-default state has been reviewed and the non-default tests have been removed or updated to reflect the post-removal code path. A lifecycle specification that does not include all three conditions leaves gaps that the cleanup script will exploit. Connect this section to the incident severity classification decision record: the flag taxonomy and the incident severity classification serve the same structural purpose — both are decision taxonomies that must be applied at the moment a decision is made, not retrospectively after consequences have accumulated; the severity classification decision requires classifying an incident at its start, before all facts are known, using a rubric that specifies which observable conditions map to which severity levels; the flag taxonomy decision requires classifying a flag at its creation, before its full impact on the codebase is known, using a rubric that specifies which flag purposes map to which lifecycle categories; both classifications determine the process that follows — an incorrectly classified severity triggers the wrong response protocol, an incorrectly classified flag triggers the wrong lifecycle governance, and both errors are more costly to correct after the fact than to prevent through a well-specified classification rubric applied at decision time.

Section 2: Flag testing strategy and the state coverage model. Specify the testing strategy for each flag category, the minimum coverage requirement for each flag configuration state, and the mechanism for maintaining fixture currency as the system around the flags changes. The state coverage model must address three questions: which configuration states must be tested (the required states), how the required states are determined as new flags are added (the state matrix update process), and how the team detects when the test fixtures for non-default states have drifted from the current production configuration (the fixture currency check). The required states for a single flag are: the default state and the non-default state, both tested against the current production schema and configuration, not against fixtures created at the time the flag was introduced. The required states for a cluster of interacting flags are: the all-default state, the all-non-default state, and any partial states that represent real production configurations — accounts mid-migration, environments with specific flag combinations for operational reasons. The state matrix update process must be triggered by two events: a new flag is introduced that interacts with an existing flag (requiring new combined-state tests), and a schema or configuration change is made to the system that affects a code path controlled by an active flag (requiring fixture updates for all affected flag states). The fixture currency check is a CI step that verifies that the test fixtures for non-default flag states match the current production schema for the relevant tables and API contracts; this check is most efficiently implemented as a schema hash comparison between the production migration state and the test fixture state, with a CI failure when they diverge. A fixture currency check that runs as part of CI and fails visibly is more effective than a review process that relies on engineers to remember to update fixtures when they change schemas. Connect this section to the observability strategy decision record: the fixture currency check and the observability model accuracy check are the same type of metacognitive verification — both are mechanisms for detecting when the measurement system has drifted from the reality it is measuring; the observability strategy must include a process for verifying that the metrics, dashboards, and alert thresholds accurately represent the current system architecture; the flag testing strategy must include a process for verifying that the test fixtures accurately represent the current production configuration for all flag states; both processes are frequently omitted because they require effort to maintain and because their absence is invisible until an incident reveals that the measurement system was reporting accurate numbers about a configuration that production had not been running for months.

Section 3: Flag ownership model and the handoff protocol. Specify the flag ownership model — who owns a flag throughout its lifetime, what facts the owner is responsible for maintaining in the flag registry, and what the handoff process is when the owner's context changes. The ownership model must address the knowledge decay surface explicitly: for each flag category, specify the minimum set of facts that must be documented in the flag registry at creation time and maintained by the owner throughout the flag's lifetime. For a permission toggle, the minimum fact set includes: the account or user population in the non-default state (with the production query used to enumerate them, not a static count), the migration plan and its current status, the owner's name and team, and the removal criteria that must all be satisfied before the flag is eligible for cleanup. The handoff protocol specifies the process for transferring flag ownership when an owner's context changes — when they move to a different feature area, join a different team, or leave the company. The handoff is not a name change in a registry: it is a knowledge transfer meeting between the outgoing owner and the incoming owner in which the incoming owner confirms they can answer all the questions in the minimum fact set from their own understanding, not from reading the registry. A handoff that consists of updating a CSV file is an ownership record, not an ownership transfer. The ownership model must also specify who is responsible for flags with no active owner — flags whose documented owner has left the company or whose documented team no longer exists. These flags require an audit and assignment process, not a cleanup script: a flag with no owner cannot be safely cleaned up by a script that does not know what population is in the non-default state, what behavior they depend on, or whether a migration is in progress. Connect this section to the runbook quality decision record: flag ownership and runbook ownership share the same structural requirement — both require a named owner who is responsible for maintaining the artifact's accuracy over time, a handoff protocol when the owner changes, and a monitoring mechanism for detecting when the artifact's content has drifted from the current system state; a runbook whose documented author has left the company is a maintenance liability — it may be accurate or it may have accumulated drift, and there is no mechanism to distinguish the two without a review; a flag whose documented owner has left the company is a cleanup liability — it may be safe to remove or it may be controlling critical production behavior, and there is no mechanism to determine which without reconstructing the context the departing owner carried; both artifacts require governance structures that treat owner departure as a trigger for a handoff review, not a trigger for the artifact to persist indefinitely with a stale owner record.

Section 4: Flag cleanup governance and the accumulation detection threshold. Specify the cleanup governance process — how the team identifies flags that are eligible for removal, how cleanup candidates are validated before removal, and how the cleanup is executed to minimize the risk of removing a flag that is still load-bearing. The accumulation detection threshold is the flag count at which the team activates a dedicated cleanup cycle rather than addressing individual flag debt as it accumulates; for most engineering teams this threshold is between 30 and 50 active flags, beyond which the cognitive load of flag-conditional reasoning becomes a productivity tax that justifies a dedicated cleanup sprint. The cleanup validation process must address the knowledge decay problem: a flag that was documented at creation as a release toggle for a feature that launched 18 months ago looks like a cleanup candidate from the registry; it may be safe to remove, or it may have been silently repurposed as an access control mechanism for a specific account segment, or it may have a stalled migration with 140 accounts still in the non-default state; the cleanup validation for any flag older than 90 days must include a direct query against the production data to enumerate any accounts or environments currently in the non-default state, not a query against a derived permission model. The cleanup execution process for flags with a non-empty non-default population must be distinct from the process for flags with an empty non-default population: an empty-population flag can be removed in a standard PR with standard review; a non-empty-population flag requires a migration plan, a migration execution, a post-migration verification, and a cleanup window after the migration before the flag itself is removed. A cleanup script that removes flags without distinguishing between these two cases — as the cleanup script in the third story did — is removing flags faster than the validation process can confirm they are safe to remove, which is the operational equivalent of deploying without testing. Connect this section to the on-call load management decision record: the flag accumulation threshold and the on-call alert volume threshold are both indicators of a system that has grown beyond a sustainable operating point; the on-call load management decision specifies the maximum alert volume per engineer before rotation coverage and response quality degrade; the flag cleanup governance specifies the maximum active flag count before the cognitive load on engineers reading and modifying flagged code becomes a productivity liability; both thresholds exist to prevent the gradual accumulation of operational debt from crossing a point where the cost of addressing it in one sprint exceeds the accumulated carrying cost of ignoring it; and both thresholds should be treated as engineering health metrics reviewed at the same cadence as deployment frequency and incident rate, because both have the same property — they are invisible costs that accumulate silently and become visible only when they cause an incident or a significant productivity degradation.

Section 5: Rollback surface specification and the flag-incident response protocol. Specify the rollback surface for each flag category — what state can be restored by flipping a flag, what state cannot be restored by flipping a flag, and what the protocol is for using flag state changes as a rollback mechanism during an incident. The rollback surface is not always symmetric: a flag flip from non-default to default can restore the pre-migration code path, but it cannot restore data that was written in the migrated schema format to accounts that have already been migrated; a flag flip from enabled to disabled can disable a new feature, but it cannot undo side effects that the feature has already produced — emails sent, notifications triggered, webhooks fired, audit records created. The rollback surface specification must document, for each active flag: what state changes are reversible by flipping the flag, what state changes are irreversible (and therefore require a separate recovery plan if the migration must be rolled back), and the side effects that will be produced by a flag flip in either direction. This specification exists to prevent an incident responder from flipping a flag as a rollback mechanism and discovering, mid-incident, that the flip produced a different set of side effects than expected. The flag-incident response protocol specifies the steps for identifying whether a flag change was involved in a production incident, the process for querying the flag interaction map to identify secondary flags whose behavior is affected by a change to the primary flag, and the communication protocol for notifying account owners when a flag change affects their account's behavior. Connect this section to the incident severity classification decision record: the rollback surface specification is an input to the severity classification at the start of a flag-change incident — an incident whose rollback surface includes irreversible schema changes is a higher severity than an incident whose rollback surface is fully reversible by a flag flip, because the time window for mitigation is narrower and the potential blast radius of continued migration is larger; the severity classification rubric should include a flag-change incident category that triggers an immediate query of the rollback surface specification for the changed flag, so that the incident commander knows at the start of the incident whether the mitigation options include a simple flag flip or require a more complex recovery sequence; the absence of a rollback surface specification means the incident commander learns the rollback options through incident diagnosis rather than from pre-documented specifications, which adds hours to the diagnosis in exactly the scenarios where hours are the most expensive.

FAQ

Further reading

• Incident severity classification decision record — flag accumulation and undocumented flag interactions are a leading contributor to incident severity miscalibration at the start of flag-change incidents: the visible symptom — elevated error rates for a subset of accounts — maps to a lower severity tier than the actual blast radius once the cascade of undocumented flag interactions is traced, and the severity classification rubric must include a flag-change incident category that triggers an immediate interaction map query before the initial severity assessment is finalized; a flag interaction that is undocumented at incident start is a hidden severity escalation risk that the classification rubric cannot account for until the post-mortem reveals it.
• Observability strategy decision record — the state coverage gap between tested and production flag configurations is the same observability problem as the gap between monitored and actual system behavior: both are gaps between the measurement system's model of what is happening and what production is actually doing; the observability strategy must include a mechanism for detecting when the monitoring model has drifted from the system; the flag testing strategy must include a fixture currency check that detects when the non-default-state test fixtures have drifted from the current production schema; both are metacognitive verification steps whose absence is invisible until an incident reveals that the measurement system was reporting accurate numbers about a configuration that production had stopped running months earlier.
• Runbook quality decision record — flag ownership decay and runbook authorship decay are the same knowledge management failure at different levels of abstraction: a runbook whose author has left the company may be accurate or may have accumulated drift from the infrastructure changes that followed the author's departure; a flag whose owner has left the company may be safe to remove or may be controlling critical production behavior for an account segment whose migration stalled when the owner's context moved on; both artifacts require governance structures that treat owner departure as a trigger for a handoff review, not as a trigger for the artifact to persist indefinitely with a stale owner record; and both produce their worst failures when a cleanup process — a runbook review that flags a step as deprecated, or a flag cleanup sprint that marks a flag as a retirement candidate — acts on incomplete knowledge about the current production dependency on the artifact being cleaned up.
• On-call load management decision record — flag accumulation and on-call alert volume are parallel accumulation problems with parallel governance solutions: both grow monotonically when the mechanism that triggers reduction is absent or insufficiently specified; the on-call load management decision specifies the maximum alert volume per engineer before rotation coverage and response quality degrade; the flag management decision specifies the maximum active flag count before the cognitive load on engineers reading flagged code becomes a productivity tax; both thresholds should be treated as engineering health metrics reviewed at the same cadence as deployment frequency and incident rate, because both accumulate silently and become visible only when they cross the threshold that triggers a production incident or a measurable productivity degradation.
• Developer experience measurement decision record — flag accumulation is a leading indicator of developer experience degradation through the cognitive load channel that DORA metrics and SPACE Activity dimension scores cannot detect: a codebase with 140 active flags imposes a flag-reasoning overhead on every engineer who modifies flagged code, reducing the depth of focus per code change and increasing the context-switch frequency per feature cycle; the developer experience measurement system should include flag count as a proxy metric for code complexity growth, alongside flow state frequency and review wait time, and should track its correlation with Efficiency and Satisfaction SPACE dimensions to establish whether flag accumulation is predictive of developer experience degradation in the team's specific context; DORA deployment frequency metrics will continue to report elite-tier performance while flag accumulation is degrading the quality of each individual engineer's contribution window.
• Open-source extractor — find the feature flag management decisions buried in your AI chat history: the planning session where the team decided to adopt trunk-based development and feature flags as the release mechanism, at a time when the codebase had 3 active flags and the lifecycle governance question felt premature; the retrospective where someone mentioned that the flag count had reached 80 and the team noted it as a technical debt item without specifying what "address the flag debt" meant as an actionable task; the architecture discussion where an engineer proposed a flag registry and the team agreed it was a good idea without assigning an owner, a data model, or a migration path for the 80 flags that already existed without registry entries; and the incident post-mortem that first documented the flag interaction map concept as a recommendation, 14 months after the lifecycle model decision that made the interaction map necessary — recoverable decision records that, retrieved together, show the progression from a deliberate adoption decision to a governance gap to an incident, and that make the feature flag management ADR easier to write correctly the second time because the failure mode is explicitly documented in the decisions that led to it.