flag-removal-runbook-author

Overview

Stale feature flags are technical debt: they bloat the codebase, expand the flag-state matrix per feature-flag-test-matrix-reference, and confuse readers. But removing a flag wrong - deleting code that's actually still gated for some users - is a regression.

This skill produces the runbook for safely removing a flag.

When to use

• A flag is at 100% rollout for ≥ 2 weeks.
• An experiment has shipped; the variant code paths need consolidation.
• A kill-switch hasn't been activated for ≥ 6 months.
• Stale-flag audit (per stale-flag-detector) surfaced the flag.

Step 1 - Pre-removal verification

Before any code touches:

Failure of any check = abort and resolve first.

Step 2 - Identify dependent code

Grep:

grep -rn 'show-new-ui\|"show-new-ui"' --include='*.{ts,js,py,go,java}' .

For each match, classify:

Step 3 - Code removal

For boolean flag at 100% rollout = true:

// Before
if (client.isOn('show-new-ui')) {
  return <NewHeader />;
} else {
  return <OldHeader />;
}

// After
return <NewHeader />;

Delete <OldHeader /> component if not used elsewhere. Use TypeScript / linter to find unused imports.

For multi-variant flag with treatment-b shipped:

// Before
const variant = client.getFeatureValue('checkout-experiment', 'control');
if (variant === 'treatment-a') { ... }
else if (variant === 'treatment-b') { ... }
else { ... }  // control

// After (only treatment-b retained)
// (inline treatment-b's logic here)

Keep the shipped variant's logic, inlined. Delete the others.

Step 4 - Update tests

Per flag-state-coverage-builder:

• Remove the per-flag isolation tests for this flag.
• Update any matrix that included this flag.
• Update the flag-coverage.yaml to remove entries.
• Keep any test that asserts the new behaviour (it's no longer flag-gated - it's just the behaviour).

# Find tests referencing the flag
grep -rn 'show-new-ui' tests/

Step 5 - Platform-side removal

Archive instead of delete where possible - retains historical analytics in case of regression.

Step 6 - Deploy

Standard deploy. The flag is now:

• Removed from code
• Archived in the platform
• No longer in the test matrix

Production should see identical behaviour as before removal.

Step 7 - Post-removal verification

Within 24h of deploy:

If any check fails → roll back (revert the removal commit).

Step 8 - Rollback plan

# If removal regresses something
git revert <removal-commit>
git push
# Then in the platform: un-archive the flag and re-set its prior value

The rollback plan must be in the PR description for the removal - not memorized.

Step 9 - Document the removal

Add to the project's flag-history.md:

## 2026-05-20 — Removed `show-new-ui`

- Rolled out 100% on 2026-04-15
- Stable for 5 weeks at 100%
- Removed in commit abc1234
- Archived in LaunchDarkly
- Owner sign-off: @engineering-lead
- Rollback plan: revert + un-archive

Multi-flag removal batching

For stale-flag audits surfacing multiple removals: batch is faster but riskier. Per stale-flag-detector:

Anti-patterns

Output

This skill produces:

• A per-flag removal PR (code + tests + coverage-doc updated).
• A platform-side checklist for the archive action.
• A 24h post-deploy verification plan.
• A rollback-ready PR description.
• A line in flag-history.md.

References

• LaunchDarkly archive doc: launchdarkly.com/docs.
• Companion catalogs: feature-flag-test-matrix-reference, flag-state-coverage-builder.
• Detector: stale-flag-detector.
• Sibling SDKs (for platform-specific archive steps): launchdarkly-testing, unleash-testing, flagsmith-testing, growthbook-testing.