/flag-cleanup

name: flag-cleanup
description: Run the quarterly feature-flag cleanup workflow on the current repo

/flag-cleanup

Run the full feature-flag cleanup workflow:

1. Scan for stale flags (older than 90 days, used in ≤2 places) 2. For each candidate, identify the introducing PR/issue and current owner 3. Generate a removal plan grouped by owner 4. Run kill-switch audit against the flag-doc registry 5. Output a markdown report ready to share with the team

Usage

/flag-cleanup
/flag-cleanup --max-age-days 60
/flag-cleanup --flag-doc runbooks/flags.md

Implementation

This command dispatches to the `feature-flags-architect` skill:

SKILL=engineering/feature-flags-architect/skills/feature-flags-architect

# Step 1: scan for debt
python "$SKILL/scripts/flag_debt_scanner.py" --repo . --max-age-days "${MAX_AGE_DAYS:-90}" --format json > .flag-debt.json

# Step 2: audit kill switches
python "$SKILL/scripts/kill_switch_audit.py" --repo . --flag-doc "${FLAG_DOC:-docs/feature-flags.md}" --format json > .kill-switch-audit.json

# Step 3: synthesize a markdown report
# (Claude reads both JSON files, groups by owner, drafts the cleanup plan)

Output

A markdown report with:

• **Stale flag candidates** grouped by owner, with introducing commit links
• **Undocumented flags** that fail the kill-switch audit
• **Incomplete documentation** (missing fields per flag)
• **Suggested removal PRs** — one per owner

Pre-conditions

• Run from a git repository with the source code committed
• A flag-doc registry exists (default: `docs/feature-flags.md`)
• The `feature-flags-architect` skill is installed

Post-conditions

• `.flag-debt.json` and `.kill-switch-audit.json` written to repo root (ignored via `.gitignore`)
• Markdown report streamed to terminal
• Recommended next step printed (which removal PR to start with)