cleaning-up-stale-feature-flags

Call posthog:feature-flag-get-all with active: "STALE". This returns all stale flags in a single request — PostHog handles the staleness detection server-side using the criteria described above.

For each stale flag, gather context before recommending action:

Check if it's tied to an experiment:

The posthog:feature-flag-get-definition tool returns an experiment_set field. If non-empty, the flag is used by an experiment — check the experiment status before touching it.

Check if other flags depend on it:

Feature flags can have dependencies (flag B only evaluates when flag A is true). The flag definition includes dependency information in its filters. Look for flag_key references in other flags' filter groups.

Check when it was last modified:

A flag last updated years ago with no recent calls is a stronger removal candidate than one updated last month with no calls (it might be newly deployed and waiting for a release).

Summarize for the user:

For each stale flag, present:

• Flag key and description
• Why it's considered stale (no calls in N days, or fully rolled out for N days)
• Whether it's tied to experiments
• When it was created and last modified
• A recommended action (clean up from code and disable, or keep with explanation)

Generate a cleanup prompt the user can run in their code editor or coding agent. The cleanup instructions must be tailored to each flag's rollout state, because the rollout state determines which code path to keep. This list also serves as the approval checklist — if the user says their code is already cleaned up, they review it and confirm which flags to disable.

Classify each flag into one of three rollout states based on its definition:

• fully_rolled_out: A boolean flag with a release condition at 100% rollout and no property filters, or a multivariate flag where one variant is at 100%. Record which variant was active (for multivariate flags).
• not_rolled_out: All release conditions are at 0%, or the flag has no release conditions at all.
• partial: Everything else — the flag had some targeting but wasn't fully rolled out or fully off.

Then generate instructions following this structure:

For fully rolled out boolean flags — remove the flag check but keep the enabled code path:

Search for: isFeatureEnabled, useFeatureFlag, getFeatureFlag, posthog.isFeatureEnabled, posthog.getFeatureFlag

For flag "example-flag":
- Remove the if-check, keep the body
- If there is an else branch, remove the else branch entirely

For fully rolled out multivariate flags — keep only the winning variant's code:

For flag "example-flag" (keep variant: "winning-variant"):
- For if/else chains: keep only the branch matching "winning-variant", remove the flag check
- For switch statements: keep only the winning variant's case, remove the switch

For not-rolled-out flags — remove the entire flag check AND the enabled code path:

For flag "example-flag":
- Remove the if-check AND its body (the feature was never active)
- If there is an else branch, keep only the else body

For partial rollout flags — flag these for manual review:

For flag "example-flag":
- This flag had a partial rollout — check the flag's intent to determine which code path to keep
- Then remove the flag check

End the instructions with: "After cleanup, remove any dead code branches and unused imports."

Present the full cleanup prompt in a copyable format so the user can paste it directly into Claude Code, Cursor, Copilot, or any other AI code editor.

Never disable flags before the code changes are deployed. Disabling a fully rolled out flag while code still checks it will cause that code path to stop working — a production regression.

Never disable flags without explicit user approval. Always present the list and recommendations first, then ask which flags to act on.

Present the user with both options and their tradeoffs:

• Disable via posthog:feature-flag-disable: The flag stops being evaluated but the configuration is preserved. The tool takes only the flag id, so targeting cannot change. If something was missed in the code cleanup, re-enabling is instant. Recommended as the default.
• Delete via posthog:delete-feature-flag: A soft-delete — the flag is marked as deleted but not physically removed. Keeps the flag list clean, but re-enabling requires recreating the flag. Better for flags the user is confident they'll never need again.

Once the user has chosen and confirms their code changes are deployed, apply the chosen action one flag at a time. Confirm each action so it's easy to stop if something goes wrong.