alirezarezvani/claude-skills / engineering/skills/feature-flags-architect
feature-flags-architect
VerifiedUse before adding, rolling out or retiring a feature flag or kill switch, or when flag debt piles up. Plans the rollout with rollout_planner.py, finds stale flags with flag_debt_scanner.py and audits kill switches with kill_switch_audit.py.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.4 KB |
| assets/flag_request_template.md | markdown | 1.7 KB |
| references/flag_lifecycle.md | markdown | 5.7 KB |
| references/flag_taxonomy.md | markdown | 4.4 KB |
| references/provider_comparison.md | markdown | 5.0 KB |
| references/rollout_strategies.md | markdown | 4.9 KB |
| scripts/flag_debt_scanner.pyexecutable | script | 4.7 KB |
| scripts/kill_switch_audit.pyexecutable | script | 4.9 KB |
| scripts/rollout_planner.pyexecutable | script | 4.5 KB |
scripts/flag_debt_scanner.py
View on GitHub#!/usr/bin/env python3
"""Scan a repo for stale feature flags (Karpathy goal-driven cleanup).
Detects flag identifiers from common code patterns, dates each one by its
introducing commit, and flags items older than --max-age-days that appear in
fewer than --min-uses places as cleanup candidates.
"""
import argparse
import json
import os
import re
import subprocess
import sys
from collections import defaultdict
from datetime import datetime, timezone
FLAG_PATTERNS = [
re.compile(r'\b(?:isFlagEnabled|isEnabled|featureFlag|getFlag|flag|useFlag|useExperiment)\(\s*["\']([\w.\-:]+)["\']'),
re.compile(r'\b(?:client|ld|unleash|growthbook|statsig)\.(?:variation|isEnabled|feature|getValue|getExperiment)\(\s*["\']([\w.\-:]+)["\']'),
]
CODE_EXTS = {".py", ".js", ".ts", ".tsx", ".jsx", ".go", ".rb", ".java", ".kt", ".cs", ".rs", ".php"}
SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "dist", "build", "__pycache__", ".next"}
def _walk_code_files(repo):
for root, dirs, files in os.walk(repo):
dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
for f in files:
if os.path.splitext(f)[1] in CODE_EXTS:
yield os.path.join(root, f)
def _scan_file(path):
try:
with open(path, "r", encoding="utf-8", errors="replace") as f:
text = f.read()
except OSError:
return []
found = set()
for pat in FLAG_PATTERNS:
for m in pat.finditer(text):
found.add(m.group(1))
return list(found)
def _first_commit_date(repo, flag_name):
try:
out = subprocess.run(
["git", "-C", repo, "log", "--diff-filter=A", "--format=%cI", "-S", flag_name],
capture_output=True, text=True, timeout=10, check=False,
)
except (subprocess.SubprocessError, OSError):
return None
lines = [ln for ln in out.stdout.strip().split("\n") if ln]
if not lines:
return None
try:
return datetime.fromisoformat(lines[-1])
except ValueError:
return None
def _age_days(when):
if when is None:
return None
now = datetime.now(timezone.utc)
return (now - when).days
def collect_flags(repo):
flags_to_paths = defaultdict(list)
for path in _walk_code_files(repo):
for name in _scan_file(path):
flags_to_paths[name].append(os.path.relpath(path, repo))
return flags_to_paths
def assess(repo, flags_to_paths, max_age_days, min_uses):
rows = []
for name in sorted(flags_to_paths.keys()):
paths = flags_to_paths[name]
when = _first_commit_date(repo, name)
age = _age_days(when)
is_debt = (
age is not None
and age > max_age_days
and len(paths) <= min_uses
)
rows.append({
"flag": name,
"uses": len(paths),
"age_days": age,
"first_seen": when.date().isoformat() if when else None,
"files": paths[:5],
"is_debt": is_debt,
})
return rows
def render_text(rows, max_age_days):
debt = [r for r in rows if r["is_debt"]]
print(f"Flag Debt Scanner — {len(rows)} flags found, {len(debt)} stale (>{max_age_days}d, ≤2 uses)")
print("")
if not debt:
print("No debt detected. Nice.")
return
print(f"{'flag':40} {'age':>6} {'uses':>4} files")
print("-" * 80)
for r in debt:
files = ", ".join(r["files"][:2]) + ("…" if len(r["files"]) > 2 else "")
age = f"{r['age_days']}d" if r["age_days"] is not None else "?"
print(f"{r['flag']:40} {age:>6} {r['uses']:>4} {files}")
print("")
print("Suggested action: confirm reached 100% (or killed); delete dead branch; remove flag.")
def main():
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--repo", default=".", help="Path to repo root (default: .)")
ap.add_argument("--max-age-days", type=int, default=90, help="Flags older than this are debt candidates (default: 90)")
ap.add_argument("--min-uses", type=int, default=2, help="Flags with ≤ this many uses are debt candidates (default: 2)")
ap.add_argument("--format", choices=["text", "json"], default="text")
args = ap.parse_args()
repo = os.path.abspath(args.repo)
if not os.path.isdir(os.path.join(repo, ".git")):
print(f"WARN: {repo} is not a git repo; age detection disabled", file=sys.stderr)
flags = collect_flags(repo)
rows = assess(repo, flags, args.max_age_days, args.min_uses)
if args.format == "json":
print(json.dumps(rows, indent=2, default=str))
else:
render_text(rows, args.max_age_days)
return 1 if any(r["is_debt"] for r in rows) else 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |