feature_flag_discipline v1.0.0

name: feature_flag_discipline description: Create, roll out, and clean up feature flags with a hard lifecycle: type taxonomy, naming rules, a staged rollout ladder, safe defaults, and a mandatory cleanup commitment at creation. Triggers on "feature flag", "feature toggle", "kill switch", "gradual rollout", "flag debt", "dark launch", or cleaning up stale flags.

Feature Flag Discipline

Purpose

Feature flags decouple deploys from releases, but flags left lying around become debt that slows every future change. This skill gives an agent the full lifecycle: classify the flag, name it, write it down with a cleanup date, roll it out in reversible steps, then delete it and the dead code on time. The cleanup commitment is made at creation, not "later."

Workflow

1. Classify the flag

Every flag belongs to exactly one type. The type decides the default state and the lifetime.

| Type | Job | Default | Lifetime | |---|---|---|---| | release_ | Ship code dark, enable later | Off | Temporary: gone within 90 days of 100% rollout | | exp_ | A/B or experiment variant | Control bucket | Temporary: experiment duration + ~30 days | | ops_ | Kill switch, circuit breaker | On (normal behavior) | Permanent, reviewed annually | | perm_ | Entitlement or segment gating | Off (not granted) | Permanent, reviewed annually |

If it is tied to one feature launch, it is a release flag, and it must die. Only ops and permission flags are allowed to live forever.

2. Name it

snake_case, type-prefixed, describing the capability, not the change: release_search_semantic_v2, exp_checkout_single_page, ops_kill_switch_video_upload, perm_premium_export_csv. Never a ticket number, never a date, keep it under 50 characters, and give it a one-line owner and cleanup date in the registry at creation. No registry entry, no flag.

3. Evaluate safely

• Default-off for release and experiment flags. The feature must be explicitly enabled, never on by surprise.
• The default used when the flag system is unreachable must be the safe state: the app still works. Kill switches evaluate server-side and must work without a deploy.
• Never nest flags more than 2 levels deep. Never put secrets in flags. Never trust a client-side flag for security decisions; verify server-side.

4. Roll out in reversible rungs

self -> team -> small percentage -> larger percentage -> everyone. A reasonable ladder: 1%, 10%, 50%, 100%, with at least 24 hours of monitoring between steps. Every rung is reversible from the console or dashboard without a deploy, and the rollback plan is written in the PR before rollout starts. Monitor error rate and the metric that motivated the feature at each rung.

For anything that acts on data (spam classification, billing, deletes), run in shadow mode first: execute the new logic, act only when the flag is on, and log what would have happened otherwise. A disabled flag still reports whether the rollout is safe.

5. Graduate: delete the flag and the dead code

A flag at 100% with both paths still in the code is debt. Graduation means: remove every flag check, delete the losing branch, remove the registry entry, delete the flag in the provider, and update the tests so they exercise the surviving path only. Ship it within 30 days of full rollout for release flags.

6. Audit flag debt regularly

Run bin/flag_audit.py against your flag registry (YAML). It flags: names that break the convention, flags past their cleanup date, and release/experiment flags older than 90 days without a renewal. Review permanent ops/permission flags annually. Delete deactivated flags that no longer have code referencing them.

Output Contract

When asked to create or manage a flag, return a registry entry with:

yaml
- name: release_search_semantic_v2
  type: release
  owner: search-team
  created: 2026-10-07
  cleanup_by: 2027-01-07
  default: false
  rollback: disable flag in dashboard (no deploy needed)
  rollout_plan: self -> team -> 1% -> 10% -> 50% -> 100%

Plus the code snippet that evaluates it in the project's actual flag system, the tests covering both paths, and the cleanup date as a calendar reminder, not a vague intention.

Operating Rules

1. Every flag gets a cleanup date at creation. A flag without one is not finished.
2. Release and experiment flags are temporary. Past 90 days without a documented renewal, they are debt and get scheduled for removal.
3. Both code paths are tested while the flag is active. No path left unverified.
4. Ops flags are permanent but earned: a kill switch stays only if the incident response plan names it.
5. Cleanup is not complete until the code branches are gone. Deactivating in the dashboard without removing the checks does not count.
6. One flag, one type. If it feels like two flags, it is two flags.