Launchdarkly Flag Drift

LaunchDarkly Flag Drift Detection

You're using a skill that will guide you through checking whether a feature flag's in-code SDK fallback default has drifted from its LaunchDarkly default rule (fallthrough), and reconciling the code if it has. Your job is to determine the flag's current default rule value from LaunchDarkly, locate the default argument passed to every SDK evaluation in code, compare them, and, only when they differ, update the in-code default so it matches. You never remove the flag or change its evaluation logic.

Prerequisites

This skill requires the remotely hosted LaunchDarkly MCP server to be configured in your environment.

Required MCP tools:

• get-flag: fetch the flag's configuration in a specific environment (fallthrough, variations, offVariation). Fallthrough is environment-specific, so call this once per critical environment.

Optional MCP tools:

• list-flags: find the flag key if the user only described the flag by name
• get-environments: enumerate the project's environments to determine which are critical
• get-flag-status-across-envs: quick snapshot of a flag's state across environments (a fast way to spot cross-environment differences before pulling each get-flag)

Core Concept: The SDK Fallback Default Is Not the Off Variation

Every SDK evaluation call takes a fallback default: the value returned when LaunchDarkly is unreachable, the client is uninitialized, or the flag is unavailable. This is a code-side safety value, distinct from the flag's offVariation (served when the flag is toggled off) and from its fallthrough (the default rule served when no targeting rule matches).

This skill treats one specific invariant as "correct": the in-code fallback default should match the current default rule (fallthrough) value. When they diverge, that's drift. Reconciling it keeps the value returned during an outage consistent with what most users would otherwise receive.

Core Concept: One In-Code Default, Many Environments

The in-code fallback default is a single value compiled into the deployed code. The flag's fallthrough, however, is configured per environment and can differ between them (e.g. production, eu-production, and federal may each serve a different default rule). So the fallthrough must be resolved in every critical environment the code runs against, not just one.

• When the critical environments agree on the fallthrough, that shared value is the expected default. Reconcile as normal.
• When they disagree (e.g. EU serves true but Federal serves false), a single in-code default cannot match all of them. That divergence is itself a finding: surface it and confirm which environment is authoritative for this build rather than silently reconciling to one. See Edge Cases.

Checking only one environment is the most common way this skill produces a wrong or misleading result, so always establish the full set of critical environments first.

Some teams intentionally keep the fallback as a conservative/off value instead. Treat a mismatch as a finding to surface, not always an automatic edit. See Edge Cases.

Workflow

Step 1: Identify the Flag and the Critical Environments

1. Get the flag key. If the user described the flag by name, use list-flags to resolve the key. Confirm before proceeding.
2. Establish the critical environments. The fallthrough is environment-specific, and the same in-code default has to stand in for every environment the deployed code serves. Determine that full set before comparing:
   • If one build serves multiple production-grade environments (e.g. production, eu-production, federal), all of them are critical.
   • If the build is scoped to one environment (a region- or tenant-specific deployment, e.g. a Federal-only build), that single environment is the only critical one.
   • Look for signals in the repo (deploy config, environment names in CI, SDK key wiring) and confirm with the user. Use get-environments to enumerate what exists if the set is unclear. Do not assume a single production.

Step 2: Determine the Expected Default from LaunchDarkly

Call get-flag once per critical environment. For each environment, read:

• fallthrough: the default rule. If it points to a single variation (an index), that's the resolved value. If it's a percentage rollout, there is no single default value, so stop and handle as an edge case.
• variations: map fallthrough.variation (the index) to variations[index].value. This resolved value is that environment's expected default.
• offVariation and flag type: useful context for the comparison and for spotting type mismatches.

Then reconcile across environments:

(get-flag-status-across-envs can give a fast heads-up on whether environments differ, but always resolve the actual fallthrough value with get-flag before editing.)

Never guess the fallthrough value. Always resolve it from get-flag.

Step 3: Locate Every In-Code Default

Find every place the flag is evaluated in code and, critically, the default/fallback argument passed to the SDK call. Search for the flag key across the codebase, then identify the default in each hit.

• The default is typically the last positional argument to variation(...) / *Variation(...) calls (e.g. boolVariation("<key>", context, <default>)).
• Teams often wrap the SDK. Check wrapper/registry/config layers that declare a default once per flag, annotation- or struct-tag-based defaults, and generated default files.

See SDK Default Patterns for the full set of patterns by language and abstraction, and how to distinguish the default argument from the context argument.

Step 4: Compare and Decide

Normalize both sides before comparing (see Edge Cases for JSON/number/type notes), then:

Step 5: Reconcile the In-Code Default

Update only the default/fallback argument so it matches the expected value.

• Do not change evaluation logic, branching, or off-path behavior.
• Do not remove the flag or its evaluation.
• If the default lives in a generated file, do not hand-edit it. Update the source of truth (the constructor/registry/annotation) and regenerate using the project's codegen command. Note requires_generation: true in your summary.

Example (before then after), expected default = true:

// Before: outage returns false even though the default rule now serves true
const enabled = await ldClient.variation('new-checkout-flow', context, false);

// After: fallback default reconciled to match the fallthrough
const enabled = await ldClient.variation('new-checkout-flow', context, true);

The surrounding if (enabled) { ... } else { ... } branching is left untouched.

Step 6: Validate Before Committing

Run the project's configured checks scoped to the changed files. Discover them from package.json scripts, a Makefile, AGENTS.md/CLAUDE.md/CONTRIBUTING.md, or the CI config. Typically: format, lint, type-check, build, and the relevant tests.

Hard stop: if any check fails and you cannot fix it, do not commit or push. Narrow your change instead. Never ship code that fails format/lint/type-check/build/test.

Step 7: Open the Pull Request

Only after validation passes. Use references/pr-template.md. The description must state: the flag key, the critical environments checked and their resolved fallthrough values, the old vs new in-code default, and that only the SDK fallback default changed (the flag and its evaluation are preserved).

• Follow the repository's contribution conventions (branch naming, commit style). Check AGENTS.md/CLAUDE.md/CONTRIBUTING.md first.
• A clear default: branch fix/flag-default-drift-<flag-key>, commit fix: sync in-code default for <flag-key> to match fallthrough.

Step 8: Report a Structured Summary

Produce a concise summary with these fields:

flag_key:              <key>
environments_checked:  [<env>: <resolved fallthrough value>, ...]
environments_diverge:  true | false
drift_detected:        true | false
old_default:           <in-code value before, or n/a>
new_default:           <expected value / value written, or n/a>
files_modified:        [<paths>]
pr_url:                <url or null>
requires_generation:   true | false
notes:                 <anything the reviewer should know, incl. any cross-environment divergence>

Edge Cases

What NOT to Do

• Don't remove the flag or its evaluation; this skill only touches the default argument.
• Don't change evaluation logic, branching, or off-path behavior beyond the fallback default.
• Don't check only one environment; resolve the fallthrough in every critical environment the build serves.
• Don't reconcile to one environment's fallthrough when critical environments disagree — a single default can't satisfy divergent environments, so surface the divergence and confirm the authoritative environment first.
• Don't hand-edit generated files; regenerate from the source of truth.
• Don't open a PR when there is no drift.
• Don't guess the fallthrough value; resolve it from get-flag.
• Don't ship code that fails format, lint, type-check, build, or tests.

References

• SDK Default Patterns: Where the fallback default lives by language, wrapper, annotation, and generated-file pattern; how to find it
• PR Template: Structured PR description for a drift reconciliation
• Flag Cleanup: If the goal is to remove the flag entirely, not reconcile its default
• Flag Targeting: If the goal is to change the default rule in LaunchDarkly instead of the code