/cleaning-up-stale-feature-flags

name: cleaning-up-stale-feature-flags
description: 'Identify stale feature flags in a PostHog project and clean up the code that checks them. Use when the user wants to find, audit, or remove unused, fully rolled out, or abandoned feature flags. When the agent can read and edit a repository it performs the code cleanup itself: tested local changes, and one draft PR per flag when the user authorizes publishing. Agents without repository access generate a tailored cleanup prompt instead. Covers staleness detection, dependency checking, retained-path rules, and the code-first ordering. This skill does not archive or otherwise change a flag in PostHog.'

Cleaning up stale feature flags

This skill guides you through finding feature flags that no longer serve a purpose and removing them safely. The ordering is fixed: clean up the code, wait for that cleanup to deploy, and only then change the flag in PostHog.

When to use this skill

• The user asks to clean up, audit, review, or remove their feature flags
• The user wants to find flags that are stale, unused, or fully rolled out
• The user asks "which feature flags can I remove?" or similar
• The user wants to reduce tech debt from old feature flags

Do not activate for an unrelated coding task that merely mentions a feature flag. Cleaning up a flag is its own job, requested by the user.

What makes a flag stale

A feature flag is considered stale when it's no longer doing useful work. PostHog tracks this with two signals:

1. **Usage-based staleness**: The flag has `last_called_at` data, but hasn't been evaluated in 30+ days. This is the strongest signal — the SDKs are no longer checking this flag. 2. **Configuration-based staleness**: The flag has no usage data (`last_called_at` is null), is 30+ days old, and is 100% rolled out (boolean at 100% with no property filters, or a multivariate flag with one variant at 100%). A fully rolled out flag with no conditions is equivalent to a hardcoded value — it can be replaced by removing the flag check from code.

Disabled flags (`active: false`) are not considered stale — they were intentionally turned off and may be kept for reactivation.

Treat configuration-based staleness more cautiously than old evaluation evidence: `$feature_flag_called` events can be missing when local evaluation is used or event capture is disabled, and a config-only signal says nothing about whether code still checks the flag.

Stale means cleanup candidate, never proof that removal is safe.

Establish what you can do

Before assessing candidates, work out which path you can complete in this session:

1. **PostHog read access only** (no repository): assess candidates, then produce the tailored handoff prompt (see "Hand off when you cannot edit the repository"). 2. **Repository read access**: additionally inspect the exact call sites and turn the handoff into a repository-specific plan. 3. **Repository write access**: make the code changes yourself and test them locally. 4. **Authorized publishing**: also open one draft PR per flag, following the host's branch, commit, and PR policy.

Filesystem access is not permission to publish. The agent host's review, commit, and PR policy always wins over this skill.

Whichever path applies, never change the flag in PostHog during this workflow. Archiving the flag belongs to a later continuation, after the user confirms the code cleanup deployed (see "After the cleanup is deployed").

When the user's request clearly authorizes cleanup and you can edit the repository, execute: pick the safest deterministic candidate and clean it up directly. Do not stop to generate a copy-paste prompt, and do not add confirmation steps for local, uncommitted code changes. One action still needs approval in the user's own words: pushing a branch or opening a PR. The availability of a git or GitHub tool is not that approval, and a push to a repository cannot be taken back. The flag itself is never changed in this workflow, with or without approval.

Workflow

1. Establish scope

• Confirm which PostHog project you are assessing flags in.
• Confirm the current repository is a plausible owner of the flag (the key appears in it, or the user says it does).
• Ask about other repositories, services, mobile apps, or workers when the flag may span independently deployed code.

One repository cleanup is not proof that every deployed consumer is gone.

• Default to cleaning one high-confidence flag first, unless the user explicitly asked for a known set.

For a set, finish one flag (through validation and its PR) before starting the next.

2. Find and assess candidates

When the user names a specific flag, start from `posthog:feature-flag-get-definition-by-key`, which returns the numeric id and the full definition in one call, and skip the list.

To find candidates yourself, call `posthog:feature-flag-get-all` with `active: "STALE"`. PostHog runs the staleness detection server-side using the criteria above. The response is one page of at most 100 flags, and `count` carries the full stale total. For a full audit, raise `offset` and call again until you have read `count` flags, or the audit you report is silently truncated. When cleaning one flag, the default, one page is enough: pick from it, and report how many stale flags went unread. One shape is missing from that list: a flag with no release conditions that was never called. The server filter matches an empty `filters` only as null or `{}`, not as the `{"groups": []}` default. When the user names such a flag, look it up by key rather than reporting it as not stale.

Narrow the list before you assess it: each candidate below costs four requests, and the dependents read scans every active flag in the team. Drop what the list already rules out, such as a recent `updated_at` or a key that reads as a kill switch, then assess the most promising handful rather than a whole page. Assess those in full, because the exclusions be