@diottodev/runic 1.0.0 → 1.1.0

package/engineering/feature-flags-architect/skills/feature-flags-architect/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: feature-flags-architect
+description: Use when adding, retiring, or auditing feature flags. Triggers on "add a flag", "ship behind a flag", "rollout plan", "kill switch", "stale flags", "flag debt", "LaunchDarkly", "GrowthBook", "Statsig", "Unleash", "Flipt", or any progressive-delivery question. Ships flag debt scanner, rollout planner, and kill-switch auditor (all stdlib Python), 4 references on flag taxonomy + provider trade-offs + rollout strategies + lifecycle, plus a /flag-cleanup slash command.
+context: fork
+version: 2.9.0
+author: claude-code-skills
+license: MIT
+tags: [feature-flags, progressive-delivery, rollout, kill-switch, launchdarkly, growthbook, statsig, unleash, flipt, release-engineering]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# Feature Flags Architect
+
+End-to-end discipline for feature flags: classify them, ship them, ramp them, and retire them. Most teams treat flags as throwaway `if`-statements; this skill treats them as a controlled lifecycle with measurable debt.
+
+## When to use
+
+- Adding a new flag and need a rollout plan
+- Auditing a codebase for stale or orphaned flags
+- Choosing a flag provider (LaunchDarkly vs GrowthBook vs Statsig vs Unleash vs Flipt vs build-your-own)
+- Designing a kill-switch path for a risky launch
+- Cleaning up flag debt before a release freeze
+- Reviewing whether a feature should ship behind a flag at all
+
+## Core principle: flags are a lifecycle, not an `if`
+
+```
+request → design → ship → ramp → cleanup → archive
+```
+
+Flags that skip cleanup become debt: dead branches, stale defaults, untested code paths, unbounded blast radius. The three scripts in this skill enforce the lifecycle.
+
+## Quick start
+
+```bash
+# 1. Audit the repo for flag debt
+python scripts/flag_debt_scanner.py --repo . --max-age-days 90
+
+# 2. Plan a progressive rollout for a new flag
+python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring
+
+# 3. Verify every flag has a documented kill switch
+python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md
+```
+
+## The 4 flag types (taxonomy)
+
+Different flag types have different lifespans and ownership. Misclassifying creates debt.
+
+| Type | Purpose | Typical lifespan | Owner | Cleanup trigger |
+|---|---|---|---|---|
+| **Release** | Hide unfinished features in production | days–weeks | Eng | 100% rollout reached |
+| **Experiment** | A/B test variants | weeks | Product/Marketing | Test concluded; winner picked |
+| **Operational** | Circuit breakers, perf toggles, kill switches | months–years | Eng/SRE | Replaced by autoscaling/feature retirement |
+| **Permission** | Entitlements per user/account/plan | years (permanent) | Product | Plan/role removed |
+
+Only Release and Experiment flags should be on a debt-scanner watchlist. Operational and Permission flags are by design long-lived. See `references/flag_taxonomy.md` for decision tree.
+
+## The 3 Python tools
+
+All three are stdlib-only. Run with `--help`.
+
+### `flag_debt_scanner.py`
+
+Finds flags older than `--max-age-days` with low usage, suggesting candidates for cleanup.
+
+```bash
+python scripts/flag_debt_scanner.py --repo . --max-age-days 90 --format text
+python scripts/flag_debt_scanner.py --repo . --max-age-days 60 --format json > debt.json
+```
+
+**Detection heuristic:**
+1. Walk `--repo` for code references matching common flag-call patterns:
+   - `flag("...")`, `isFlagEnabled("...")`, `featureFlag("...")`, `getFlag("...")`
+   - `client.variation("...", ...)`, `unleash.isEnabled("...")`, `growthbook.feature("...")`
+2. For each unique flag identifier, find the oldest commit that introduced it (`git log --diff-filter=A -S <name>`).
+3. Flag as DEBT if introduced > `--max-age-days` ago AND used in ≤`--min-uses` places.
+
+Outputs flag name, age in days, file references, suggested action. JSON mode is CI-friendly.
+
+### `rollout_planner.py`
+
+Generates a phased rollout schedule from population size, target percent, duration, and strategy.
+
+```bash
+python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring
+python scripts/rollout_planner.py --population 50000 --target-percent 25 --duration-days 7 --strategy linear
+python scripts/rollout_planner.py --population 1000000 --target-percent 100 --duration-days 30 --strategy log
+```
+
+**Strategies:**
+- `ring`: 1% → 5% → 25% → 50% → 100%, evenly spaced. Default for risky launches.
+- `linear`: constant rate per day. Default for medium-risk.
+- `log`: rapid early, slow tail. Default for low-risk launches with confidence.
+- `cohort`: by named cohort (internal → beta → free → paid → all).
+
+Outputs a markdown table with date, percent, expected user count, abort criteria, and verification step per phase.
+
+### `kill_switch_audit.py`
+
+Cross-references code-discovered flags against documentation to verify each has a kill switch path written down.
+
+```bash
+python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md
+python scripts/kill_switch_audit.py --repo . --flag-doc runbooks/flags.md --format json
+```
+
+**What it checks:**
+1. Every code-discovered flag has an entry in `--flag-doc`
+2. Each entry declares: owner, type, kill-switch trigger, monitoring dashboard
+3. Reports flags missing documentation (FAIL) or missing fields (WARN)
+
+Use as a pre-merge gate before any new flag ships.
+
+## Provider chooser (5 + DIY)
+
+| Provider | Best for | Pricing model | Lock-in risk | OSS option |
+|---|---|---|---|---|
+| **LaunchDarkly** | Enterprise, complex targeting, audit/compliance | Per-MAU, expensive | High | No |
+| **GrowthBook** | Mid-market, A/B testing focused, OSS-friendly | Per-MAU + OSS | Low | Yes (self-host) |
+| **Statsig** | Growth/product teams, advanced experimentation | Free tier + per-MAU | Medium | No |
+| **Unleash** | OSS-first, self-hosted, dev-friendly | OSS + Enterprise | Low | Yes |
+| **Flipt** | Lightweight, k8s-native, simple needs | OSS-only | None | Yes |
+| **DIY** | <100 flags, no targeting, full control | None | None | N/A |
+
+Decision rules:
+- <50 flags + no targeting → DIY with config file or env vars
+- Need analytics + experimentation → Statsig or GrowthBook
+- Compliance/SOC2 audit logs required → LaunchDarkly
+- Self-hosting required (data residency / air-gapped) → Unleash or Flipt
+- See `references/provider_comparison.md` for detail.
+
+## Workflows
+
+### Workflow 1: Ship a new feature behind a flag
+
+```
+1. Classify: which of the 4 flag types?
+   → Release (most common for engineering work)
+2. Run rollout_planner.py to design the ramp
+3. Add flag entry to docs/feature-flags.md BEFORE writing code:
+   - name, owner, type, kill-switch trigger, dashboard URL
+4. Write the code with the flag
+5. Run kill_switch_audit.py — must pass before merge
+6. Deploy at 0%; verify kill switch works
+7. Execute rollout schedule; abort if abort criteria met
+8. At 100% for 7+ days: remove flag, delete dead branch, archive doc entry
+```
+
+### Workflow 2: Quarterly flag cleanup
+
+```
+1. Run flag_debt_scanner.py --repo . --max-age-days 90 > debt.md
+2. For each flagged item:
+   a. Confirm it reached 100% (or was killed)
+   b. Find the issue/PR that introduced it; verify owner agrees to remove
+   c. Delete dead branches; remove flag config
+   d. Run kill_switch_audit.py — should now show one fewer flag
+3. Update CHANGELOG: "Removed N stale flags"
+```
+
+### Workflow 3: Choose a provider
+
+```
+1. Estimate flag count (current + 12-month projection)
+2. Required features:
+   - Targeting rules (user, account, geo, %)?
+   - A/B testing + stats?
+   - Audit log / SOC2?
+   - Self-hosting / data residency?
+3. Pricing budget (MAU * cost-per-MAU)
+4. See provider_comparison.md decision tree
+5. Build a 30-day proof-of-concept before signing
+```
+
+### Workflow 4: Design a kill switch
+
+```
+1. Identify the failure modes:
+   - Latency spike (which threshold?)
+   - Error rate spike (which threshold?)
+   - Business metric regression (which threshold?)
+2. Wire each to an abort:
+   - Manual: dashboard link + on-call playbook
+   - Automated: alert threshold flips flag back to 0%
+3. Test the kill switch in staging BEFORE production rollout
+4. Document in flag-doc; pass kill_switch_audit.py
+```
+
+## References
+
+- `references/flag_taxonomy.md` — 4 types, decision tree, ownership, lifespan
+- `references/provider_comparison.md` — LaunchDarkly / GrowthBook / Statsig / Unleash / Flipt / DIY trade-offs
+- `references/rollout_strategies.md` — ring / linear / log / cohort / geo, abort criteria, monitoring
+- `references/flag_lifecycle.md` — request → design → ship → ramp → cleanup → archive
+
+## Slash command
+
+`/flag-cleanup` — Run the full cleanup workflow on the current repo: scan for debt, generate a removal plan, audit kill switches.
+
+## Asset templates
+
+- `assets/flag_request_template.md` — fill-in form for new flag requests (name, owner, type, kill switch, rollout plan)
+
+## Anti-patterns
+
+- **Permanent flag with `if (FLAG_FOO)` 50 places** — should be a Permission flag with a runtime config, not a Release flag
+- **Flag with no owner** — when the original engineer leaves, no one cleans it up
+- **No kill switch documented** — when the feature breaks, no one knows how to disable it
+- **A/B test that ran 6 months** — pick a winner; running indefinitely is debt
+- **Flags as feature toggles for cosmetic changes** — ship via deploy, not flag
+
+## Verifiable success
+
+A team using this skill should achieve:
+- 100% of new flags pass `kill_switch_audit.py` at merge time
+- `flag_debt_scanner.py --max-age-days 90` returns ≤5 stale flags repo-wide
+- Every flag has a documented owner, type, and kill switch
+- Mean time to retire a Release flag: <60 days from 100% rollout

package/engineering/feature-flags-architect/skills/feature-flags-architect/assets/flag_request_template.md

@@ -0,0 +1,65 @@
+# Feature flag request
+
+Fill in every section before opening a PR that adds the flag.
+
+## Basics
+
+- **Name:** `<kebab-case-flag-name>` (e.g., `new-checkout-flow`)
+- **Owner:** `<your-handle@team>`
+- **Type:** [ ] Release  [ ] Experiment  [ ] Operational  [ ] Permission
+- **Created:** `<YYYY-MM-DD>`
+- **Expected cleanup:** `<YYYY-MM-DD or "permanent">`
+
+## Justification
+
+> Why a flag and not a direct deploy?
+
+(Examples: risky launch, A/B test, kill-switch needed, gradual rollout, compliance requirement)
+
+## Rollout plan
+
+> Generated by `rollout_planner.py`. Paste output below.
+
+```
+<paste output here>
+```
+
+## Kill switch
+
+- **Trigger:** `<concrete signal that flips the flag back to 0%>`
+- **Threshold:** `<numeric threshold>`
+- **Method:** [ ] Manual via dashboard URL  [ ] Automated via alert webhook
+- **Runbook:** `<link to on-call runbook>`
+
+## Monitoring
+
+- **Dashboard:** `<URL>`
+- **Key metrics to watch:**
+  - `<metric 1>` baseline: `<value>`, abort threshold: `<value>`
+  - `<metric 2>` baseline: `<value>`, abort threshold: `<value>`
+
+## Code locations
+
+- **Decision point:** `<file:line>` (single point of conditional)
+- **Provider used:** `<LaunchDarkly | GrowthBook | Statsig | Unleash | Flipt | DIY>`
+- **SDK:** `<sdk version / config file path>`
+
+## Tests
+
+- [ ] Test for ON branch
+- [ ] Test for OFF branch
+- [ ] Kill-switch test in staging (verify flag flip works)
+
+## Cleanup criteria
+
+> When can this flag be removed?
+
+(Example: at 100% rollout for ≥7 days with no incidents)
+
+## Pre-merge checklist
+
+- [ ] `kill_switch_audit.py` passes
+- [ ] flag-doc entry added with all required fields
+- [ ] PR description links to this template
+- [ ] Owner has write access to the provider dashboard
+- [ ] Abort criteria are concrete numbers, not vague

package/engineering/feature-flags-architect/skills/feature-flags-architect/references/flag_lifecycle.md

@@ -0,0 +1,171 @@
+# Flag lifecycle
+
+Every flag passes through 6 phases. Skipping any phase creates debt.
+
+```
+request → design → ship → ramp → cleanup → archive
+```
+
+## Phase 1: Request
+
+Triggered by an engineer or PM identifying a need.
+
+**Required:**
+- Flag name (kebab-case, descriptive: `new-checkout-flow` not `flag1`)
+- Owner (named individual; not a team)
+- Type (Release / Experiment / Operational / Permission)
+- Justification (why a flag, not direct deploy?)
+- Expected lifespan (days for Release, weeks for Experiment)
+
+**Tool:** `assets/flag_request_template.md`
+
+**Reject the request if:**
+- It's a cosmetic change with no risk → ship via deploy
+- It has no clear cleanup criteria → not a flag, refactor instead
+- It duplicates an existing flag → reuse
+
+## Phase 2: Design
+
+Before writing code. Document decisions.
+
+**Required artifacts:**
+- Entry in `docs/feature-flags.md` (or your flag registry) with: name, owner, type, kill switch, dashboard URL
+- Rollout plan generated by `rollout_planner.py`
+- Kill-switch trigger and runbook
+- Abort criteria with concrete thresholds
+
+**Code location:**
+- Single point of decision (not 5 `if (flag)` scattered)
+- Use a strategy/feature-toggle pattern at module boundary
+
+```python
+# Good: one decision at module entry
+if flags.is_enabled("new-checkout"):
+    return new_checkout(request)
+return legacy_checkout(request)
+
+# Bad: flag check scattered through the function
+def checkout(request):
+    if flags.is_enabled("new-checkout"):
+        validate_v2(request)
+    else:
+        validate_v1(request)
+    if flags.is_enabled("new-checkout"):
+        format_v2(request)
+    else:
+        format_v1(request)
+    # ... many more
+```
+
+## Phase 3: Ship
+
+Deploy with flag at **0% in production**, **100% in dev/staging**.
+
+**Verification before merge:**
+- [ ] `kill_switch_audit.py` passes
+- [ ] Both branches (on/off) covered by tests
+- [ ] Provider dashboard shows the flag at 0%
+- [ ] Kill switch tested in staging (flip to ON, observe; flip to OFF, observe)
+- [ ] Monitoring dashboard linked from flag-doc entry
+
+**Common shipping mistakes:**
+- Default-to-true in production (skip the safety wheels)
+- Test only the new path; assume the old path still works
+- Forget to update the flag-doc
+
+## Phase 4: Ramp
+
+Execute the rollout plan from `rollout_planner.py`. Hold each phase per `rollout_strategies.md`.
+
+**Decision points:**
+- After each phase: check abort criteria → hold | rollback | advance
+- Communicate progress in team channel
+- Update flag-doc with current percent and any abort events
+
+## Phase 5: Cleanup
+
+Once at 100% (or experiment concluded with a winner picked), remove the flag.
+
+**Cleanup checklist:**
+- [ ] Flag at 100% for ≥7 days (Release flags) OR test concluded (Experiment)
+- [ ] Owner confirms no rollback risk
+- [ ] Code change: delete the conditional, keep the new branch, delete the old branch
+- [ ] Delete the flag in the provider dashboard
+- [ ] Mark the flag-doc entry as ARCHIVED with date and PR link
+- [ ] Add to CHANGELOG: "Removed feature flag: <name>"
+
+**Common cleanup mistakes:**
+- Removing the flag from code but forgetting the provider config (orphaned)
+- Removing both branches (keep the new one)
+- Not updating flag-doc (audit trail lost)
+- Not running tests after removal (latent break)
+
+## Phase 6: Archive
+
+Move the flag-doc entry to an archive section. Keep the audit trail.
+
+```markdown
+## Archived
+
+### new-checkout-flow [removed 2026-04-12, PR #1234]
+- Owner: jane@team
+- Type: Release
+- Lifespan: 38 days from request to removal
+- Outcome: Shipped at 100%; no incidents
+```
+
+## Lifecycle automation
+
+| Phase | Tool / process |
+|---|---|
+| Request | `flag_request_template.md` filled in PR description |
+| Design | `rollout_planner.py` output committed to PR |
+| Ship | `kill_switch_audit.py` as pre-merge CI gate |
+| Ramp | Provider dashboard execution; abort wired to alerts |
+| Cleanup | Quarterly run of `flag_debt_scanner.py` |
+| Archive | Manual (engineer cleanup PR) |
+
+## SLAs by phase
+
+| Phase | Max duration | Trigger if exceeded |
+|---|---|---|
+| Request → Design | 7 days | Owner ping |
+| Design → Ship | 30 days | Owner ping; close request if stale |
+| Ship → Ramp start | 7 days | Owner ping |
+| Ramp → 100% (Release) | 30 days | Pause, review |
+| 100% → Cleanup | 30 days | `flag_debt_scanner.py` flags it |
+| Cleanup → Archive | 7 days | PR review reminder |
+
+## Worked example
+
+**Day 0:** Engineer files request: `new-search-relevance` Release flag, owner @bob, expected 21-day rollout.
+
+**Day 2:** Design done. flag-doc entry created. `rollout_planner.py` output: ring strategy, 5 rings over 14 days. Kill-switch: any drop in CTR > 5%, set flag to 0% via provider API.
+
+**Day 4:** Code shipped, flag at 0%. `kill_switch_audit.py` green. Smoke test passes.
+
+**Day 5:** Ring 1 — 1% rollout. CTR within bounds. Hold 48h.
+
+**Day 7:** Ring 2 — 5%. p99 latency +5% (within bounds). Hold 48h.
+
+**Day 9:** Ring 3 — 25%. CTR +2% — winning. Hold 48h.
+
+**Day 11:** Ring 4 — 50%. CTR +2.5%. Hold 48h.
+
+**Day 13:** Ring 5 — 100%. Hold 7 days for stability.
+
+**Day 20:** Cleanup PR opens — remove conditional, delete old branch.
+
+**Day 21:** PR merged. Flag deleted in provider. flag-doc entry archived.
+
+**Total elapsed: 21 days.** This is the target.
+
+## When the lifecycle breaks
+
+| Symptom | Diagnosis | Fix |
+|---|---|---|
+| Flag at 100% in code 6+ months | Cleanup phase skipped | Run `flag_debt_scanner.py` quarterly |
+| Flag has no owner | Owner left; not reassigned | Assign to team's tech-debt owner; cleanup or transfer in 30 days |
+| Two flags doing the same thing | Request phase missed dedup check | Consolidate; archive duplicate |
+| Flag-doc entry missing | Design phase skipped | `kill_switch_audit.py` must be a CI gate |
+| Flag flipped without rollout plan | Ramp phase skipped | Treat as incident; review cause |

package/engineering/feature-flags-architect/skills/feature-flags-architect/references/flag_taxonomy.md

@@ -0,0 +1,125 @@
+# Flag taxonomy — the 4 types
+
+Misclassifying a flag is the root cause of flag debt. Pick one type at the moment you create the flag.
+
+## Decision tree
+
+```
+Is the flag intended to be permanent (entitlement, plan tier, role-based access)?
+├── YES → Permission flag
+└── NO → Will it eventually be removed?
+    ├── Will it be removed when feature is fully shipped?
+    │   └── Yes → Release flag
+    ├── Will it be removed when an A/B test concludes?
+    │   └── Yes → Experiment flag
+    └── Will it remain as a circuit breaker / safety toggle?
+        └── Yes → Operational flag
+```
+
+## 1. Release flag
+
+**Purpose:** Hide an unfinished or risky feature in production while it's being built or rolled out.
+
+| Property | Value |
+|---|---|
+| Lifespan | Days to weeks (≤90 days target) |
+| Default | OFF in prod, ON in dev/staging |
+| Owner | Engineer who created it |
+| Cleanup trigger | Reached 100% rollout AND stable for 7+ days |
+| Debt risk | High — easy to forget |
+| Storage | Provider (LD/GrowthBook) or config file |
+
+**Examples:**
+- `new-checkout-flow` — gating a UI rewrite
+- `payment-v2-engine` — gating backend rewrite during cutover
+- `enable-search-relevance-v3` — A/B test of new ranking
+
+**Anti-pattern:** Release flag still at 100% in code 6+ months later. The branch the flag protects is dead code; remove it.
+
+## 2. Experiment flag
+
+**Purpose:** Run an A/B test or multivariate experiment.
+
+| Property | Value |
+|---|---|
+| Lifespan | 2-8 weeks (until significance) |
+| Default | OFF; control group |
+| Owner | Product or Marketing |
+| Cleanup trigger | Test concluded; winner shipped |
+| Debt risk | Medium |
+| Storage | Provider with experimentation features |
+
+**Examples:**
+- `homepage-headline-v2` — testing new copy
+- `pricing-page-monthly-vs-annual-default` — testing default toggle
+- `onboarding-checklist-vs-tour` — testing onboarding pattern
+
+**Anti-pattern:** Experiment running for 6 months because no one decided to call it. Either declare a winner or kill the test.
+
+## 3. Operational flag
+
+**Purpose:** Circuit breakers, kill switches, performance toggles. Designed to be flipped during incidents.
+
+| Property | Value |
+|---|---|
+| Lifespan | Months to years (long-lived by design) |
+| Default | ON (active path) |
+| Owner | SRE / on-call team |
+| Cleanup trigger | Replaced by autoscaling, retired feature |
+| Debt risk | Low — they're meant to persist |
+| Storage | Provider with low-latency global edge |
+
+**Examples:**
+- `enable-rate-limit-v2` — kill switch if v2 misbehaves
+- `disable-recommendations-engine` — emergency cutoff
+- `use-fallback-search` — degraded mode toggle
+
+**Anti-pattern:** Operational flag that no one knows how to use during an incident. Document the trigger and runbook.
+
+## 4. Permission flag
+
+**Purpose:** Entitlements per user/account/plan/role. Permanent by design.
+
+| Property | Value |
+|---|---|
+| Lifespan | Indefinite (plan/role lifetime) |
+| Default | OFF; granted by entitlement system |
+| Owner | Product (plan/role definitions) |
+| Cleanup trigger | Plan or role retired |
+| Debt risk | Very low |
+| Storage | User/account database, NOT a flag provider |
+
+**Examples:**
+- `feature.advanced-analytics` — enterprise-only
+- `feature.export-csv` — paid plans only
+- `role.admin-dashboard` — admin-only UI
+
+**Anti-pattern:** Permission flags stored in a flag provider with per-user targeting rules. Move them to your entitlements system; they're not feature flags.
+
+## Classification matrix
+
+When you can't decide, ask:
+
+| Question | If YES | If NO |
+|---|---|---|
+| Will this be at 100% in <90 days? | Release | next ↓ |
+| Will this run an A/B test? | Experiment | next ↓ |
+| Is this a kill switch / safety toggle? | Operational | next ↓ |
+| Is this a plan/role entitlement? | Permission | reconsider |
+
+If none fit: you don't need a flag. Either ship the feature directly via deploy, or use a different mechanism (config, env var, role).
+
+## Ownership rules
+
+- Every flag must have a named owner at creation
+- When the owner leaves, the flag is reassigned within 30 days or removed
+- Release flags lapse to the team's tech-debt owner if not reassigned
+
+## Lifespan SLAs
+
+| Type | Max acceptable lifespan | Cleanup automation |
+|---|---|---|
+| Release | 90 days | `flag_debt_scanner.py` |
+| Experiment | 60 days | Provider auto-stop on significance |
+| Operational | none | Annual review |
+| Permission | none | Tied to plan/role retirement |