Feature Flag Audit
Inventory every feature flag in the monorepo, classify it (release gate, kill switch, experiment, permission), report its state per environment, age, and readiness for removal. Triggers on 'flag audit
SKILL.md.claude/skills/skill-feature-flag-audit/SKILL.md
GitHubPurpose
Keep the feature-flag surface honest. The skill inventories all flags, groups them by purpose, and highlights flags that are fully rolled out or fully dark so they can be scheduled for cleanup. Complements the flag-cleanup skill, which executes the removal.
When to Invoke
- Monthly or pre-release flag hygiene pass.
- Before running
flag-cleanupon any single flag. - When ops wants a current-state report of the flag surface.
When NOT to Invoke
- Mid-incident (flag toggles are in flight; the audit will lie).
- For UI-only A/B experiments tracked outside the flag system.
Inputs
- scope (optional):
api,frontend,infra, orall(default). - environments: list, default
dev,staging,prod.
Procedure
- Collect flag names from:
infra/SSM parameter definitions.api/src/usages of the feature-flag service.frontend/src/hooks/useFeatureFlagcallers.
- Cross-reference the SSM values per environment (from Terraform state or the SSM API if available; otherwise from the
.tfvars). - Classify each flag:
release-gate— gates a new feature.kill-switch— disables a feature during incidents.experiment— A/B or percentage rollout.permission— access control.
- Compute age from the earliest
git logtouch of the flag identifier. - Mark removal candidates:
- Release gate ON in all envs for > 60 days.
- Kill switch never toggled for > 180 days.
- Emit the table plus candidate shortlist.
Outputs
Feature Flag Audit
Flag Type Dev Stg Prod Age Candidate
feature_new_search release-gate on on on 92d YES
kill_application_submit kill-switch off off off 210d YES
experiment_results_layout_b experiment 50% 50% 10% 30d no
perm_agency_admin permission on on on 420d no (permission)
Safety
- Read-only. Never toggles flags.
- Never flags a
permission-class flag for removal. - Flags sourced from code only; environment values are reported as best-known, with a staleness warning if Terraform state is older than 24 hours.
- FedRAMP: prod flag values are never written to logs or PR bodies by default; include
environments=prodexplicitly to opt in.
Examples
Example 1 — Monthly hygiene. Shortlist of 5 removal candidates; dev schedules flag-cleanup for each.
Example 2 — Pre-release sweep. Confirms no release-gate is accidentally off in staging before cutover.
Example 3 — Scoped audit. scope=frontend lists only frontend-consumed flags.
Related
.cursor/skills/flag-cleanup/— removes a fully-rolled-out flag..cursor/agents/feature-flag.md— adds new flags.