cleaning-up-stale-feature-flags

Files (3)

• SKILL.md
• example-interaction.md · references/
• handoff-prompt.md · references/

SKILL.md (first lines)

# 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
- The user asks for a feature flag hygiene review
- The user runs a weekly or recurring flag cleanup

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 means PostHog has not received recent calls. Local evaluation or disabled event capture can hide continued use.
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

First separate assessment from cleanup. A request to review or assess a flag authorizes reads and recommendations, not code edits.
Only an explicit cleanup request authorizes repository changes, subject to the checks below.
Then 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 below need both the definition and the dependents.

For each candidate you assess, gather context before recommending action.
Every read below takes only the flag's id, so issue them in one parallel tool block:

- **`posthog:feature-flags-status-retrieve`** returns the status, a human-readable `reason` for it,
  and a `rollout` object summarizing the configuration
  (`effectively_full_rollout`, `has_targeting_conditions`, `max_rollout_percentage`, `is_multivariate`).
  The status reflects recent evaluation, not rollout completeness — use `rollout` for that.
- **`posthog:feature-flag-get-definition`** returns the full definition:
  `experiment_set`, linked surveys, early access features, session replay settings, variants, and filters,
  including any `payloads` the flag carries, plus `evaluation_runtime` and `evaluation_contexts`.
  Skip this read when the by-key lookup already returned the definition.
- **`posthog:feature-flags-dependent-flags-retrieve`** lists other active flags that depend on this one.
- **`posthog:scheduled-changes-list`** with `model_name: "FeatureFlag"` and `record_id` set to the flag's id
  lists the changes queued for it. It returns executed and failed schedules too, so read the unexecuted future ones.

Exclude a candidate when any of these apply:

- tied to an experiment (`experiment_set` non-empty) — check the experiment's status before touching it
- linked to a survey (`surveys` non-empty), an early access feature, session replay settings, or used as remote configuration —
  check a linked survey's state, because a running survey still needs its flag
- an internal or permanent operational flag (kill switches, tier gates)
- disabled, archived, or deleted
- created or updated within the last 30 days, including metadata-only updates
- scheduled to change — a pending or recurring schedule rewrites the rollout after your cleanup lands,
  and the code that would react to it is gone
- depended on by other active flags

From PostHog/skills, MIT.