Feature Flags Architect
End-to-end feature flag design, rollout, and lifecycle management. Covers flag taxonomy (release vs ops vs experiment vs permission), gradual rollout patterns with blast-radius math, kill-switch runbooks, governance (who can flip what), and the flag-debt cleanup loop that keeps a codebase from drowning in stale flags.
This skill is provider-agnostic: the patterns work whether you run LaunchDarkly, Statsig, Unleash, Flagsmith, ConfigCat, GrowthBook, OpenFeature, or a homegrown system backed by Redis/DynamoDB/Postgres.
Core Capabilities
- Flag taxonomy — classify every flag as one of four types (release, ops, experiment, permission); the type sets lifetime, who flips it, and auto-expiry.
- Rollout ramps — dogfood → canary → 100% schedules with per-step blast-radius math and ramp templates by change type.
- Kill switches — ops-flag pattern with fail-open/closed decisions, runbooks, and alerting for risky dependencies or code paths.
- Governance — role-based who-can-flip-what matrix plus audit-log/retention requirements, mappable onto any flag system.
- Flag debt cleanup — quarterly inventory → classify → decide → execute → measure loop to keep flag count flat or shrinking.
- End-to-end workflows — add a release flag, build a kill switch, audit flag debt, flag-based rollback after a bad release.
Flag taxonomy — the four types
Every flag belongs to exactly one of these four types. The type determines the lifecycle, who can flip it, and whether it should auto-expire. Mixing types in one flag is a root cause of flag debt.
| Type |
Purpose |
Lifetime |
Who flips |
Auto-expire? |
| Release |
Decouple deploy from release. Ship code dark, ramp to users. |
Days to weeks |
Engineer who owns the feature |
Yes — remove after 100% rollout + 1 release |
| Ops |
Kill switches, circuit breakers, throttles. Turn off risky behavior fast. |
Permanent or long-lived |
Oncall / SRE / platform team |
No — but review quarterly |
| Experiment |
A/B test, multi-arm bandit, hold-out group. Measure causal impact. |
Weeks to months (test duration) |
Product / data / growth |
Yes — remove after winner is shipped |
| Permission |
Entitle users to features based on plan, role, beta-list. |
Permanent |
Product / billing |
No — but consolidate into entitlement system |
Decision rule when adding a flag: name the type. If you can't, the flag shouldn't exist yet — clarify intent first.
When to Use
- Designing a flag system from scratch — start with the flag taxonomy.
- Planning a risky release (DB migration, payment-provider swap, framework upgrade) — use the rollout ramp + kill switch.
- Auditing a codebase with hundreds of growing flags — use flag debt cleanup +
scripts/flag_audit.py.
- Setting up an A/B test or hold-out — covers the flag side; pair with
engineering/experiment-design for statistics.
- Building a kill switch for a third-party dependency outage — use the kill switch runbook generator.
- Defining who in the org can flip production flags — use the governance matrix.
- Building entitlements / paid-tier gating — use this for flag mechanics;
business-growth/paywall-upgrade-cro for the UX.
Clarify First
Before designing or operating flags, confirm these inputs. If any is unknown or vague, ASK — do not assume:
Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
Tools
| Tool |
Purpose |
Command |
flag_audit.py |
Scan a codebase for flag references, age, classification, and recommended action (optionally cross-reference a control-plane export) |
python scripts/flag_audit.py --path . --format markdown |
rollout_simulator.py |
Model a rollout: per-step blast radius, time-to-detect, recommended schedule |
python scripts/rollout_simulator.py --users 500000 --profile standard |
kill_switch_runbook.py |
Generate a kill-switch runbook (default state, flip procedure, validation, escalation) |
python scripts/kill_switch_runbook.py --flag ops.recs.kill_switch --feature Recommendations --dependency recs-svc |
All scripts: standard library only, argparse CLI, JSON + human-readable output. Run --help for full usage.
References
Load the reference that matches the task — keep this file lean and pull detail on demand:
- references/flag-types-and-patterns.md — the four flag types in depth, code patterns per type, evaluation-context schema, naming conventions, server-vs-client trade-offs, and storage models. Read when designing a flag system or writing the gating code.
- references/operations-governance-and-workflows.md — the standard ramp table, blast-radius math, kill-switch design, the governance matrix + audit-log requirements, the flag-debt cleanup loop, all four end-to-end workflows, the anti-patterns list, and the tooling input/output reference. Read when running a rollout, defining governance, or executing a workflow.
- references/rollout-and-kill-switch-playbook.md — rollout decision tree, ramp templates by change type, cohort/segment selection, kill-switch design, and monitoring/alerting hookup. Read when planning a specific ramp or wiring kill-switch alerting.
- references/flag-debt-and-cleanup.md — what flag debt costs, the cleanup cadence, dead-code detection, safe removal procedures, PR templates, and governance for flag count. Read when paying down stale flags.
Scope & Limitations
This skill covers: flag taxonomy and lifecycle, rollout ramps with blast-radius math, kill-switch design and runbooks, governance/audit requirements, and flag-debt cleanup — provider-agnostic across LaunchDarkly, Statsig, Unleash, Flagsmith, ConfigCat, GrowthBook, OpenFeature, and homegrown systems.
This skill does NOT cover: the statistical design of A/B tests (pair with product-team/experiment-design), the paywall/upgrade UX for entitlements (business-growth/paywall-upgrade-cro), or the metric instrumentation needed to make ramp decisions (engineering/observability-designer).
Related skills
engineering/observability-designer — wire the metrics needed to make ramp decisionsengineering/incident-commander — flag-based rollback during incidentsengineering/chaos-engineering — verify kill switches actually work under fault injectionproduct-team/experiment-design (if available) — statistical design of A/B tests behind flags
1---2name: feature-flags-architect3description: Feature flag strategy, lifecycle, and operations. Use when designing a flag taxonomy, planning a gradual rollout, building kill switches, auditing flag debt, defining governance, running progressive delivery, or rolling back via flags.4license: MIT + Commons Clause5---6
7# Feature Flags Architect
8
9End-to-end feature flag design, rollout, and lifecycle management. Covers flag taxonomy (release vs ops vs experiment vs permission), gradual rollout patterns with blast-radius math, kill-switch runbooks, governance (who can flip what), and the flag-debt cleanup loop that keeps a codebase from drowning in stale flags.
10
11This skill is provider-agnostic: the patterns work whether you run LaunchDarkly, Statsig, Unleash, Flagsmith, ConfigCat, GrowthBook, OpenFeature, or a homegrown system backed by Redis/DynamoDB/Postgres.
12
13## Core Capabilities
14
15- **Flag taxonomy** — classify every flag as one of four types (release, ops, experiment, permission); the type sets lifetime, who flips it, and auto-expiry.
16- **Rollout ramps** — dogfood → canary → 100% schedules with per-step blast-radius math and ramp templates by change type.
17- **Kill switches** — ops-flag pattern with fail-open/closed decisions, runbooks, and alerting for risky dependencies or code paths.
18- **Governance** — role-based who-can-flip-what matrix plus audit-log/retention requirements, mappable onto any flag system.
19- **Flag debt cleanup** — quarterly inventory → classify → decide → execute → measure loop to keep flag count flat or shrinking.
20- **End-to-end workflows** — add a release flag, build a kill switch, audit flag debt, flag-based rollback after a bad release.
21
22## Flag taxonomy — the four types
23
24Every flag belongs to exactly one of these four types. The type determines the lifecycle, who can flip it, and whether it should auto-expire. Mixing types in one flag is a root cause of flag debt.
25
26| Type | Purpose | Lifetime | Who flips | Auto-expire? |
27|------|---------|----------|-----------|--------------|
28| **Release** | Decouple deploy from release. Ship code dark, ramp to users. | Days to weeks | Engineer who owns the feature | Yes — remove after 100% rollout + 1 release |
29| **Ops** | Kill switches, circuit breakers, throttles. Turn off risky behavior fast. | Permanent or long-lived | Oncall / SRE / platform team | No — but review quarterly |
30| **Experiment** | A/B test, multi-arm bandit, hold-out group. Measure causal impact. | Weeks to months (test duration) | Product / data / growth | Yes — remove after winner is shipped |
31| **Permission** | Entitle users to features based on plan, role, beta-list. | Permanent | Product / billing | No — but consolidate into entitlement system |
32
33**Decision rule when adding a flag:** name the type. If you can't, the flag shouldn't exist yet — clarify intent first.
34
35## When to Use
36
37- Designing a flag system from scratch — start with the **flag taxonomy**.
38- Planning a risky release (DB migration, payment-provider swap, framework upgrade) — use the **rollout ramp** + **kill switch**.
39- Auditing a codebase with hundreds of growing flags — use **flag debt cleanup** + `scripts/flag_audit.py`.
40- Setting up an A/B test or hold-out — covers the flag side; pair with `engineering/experiment-design` for statistics.
41- Building a kill switch for a third-party dependency outage — use the **kill switch runbook** generator.
42- Defining who in the org can flip production flags — use the **governance** matrix.
43- Building entitlements / paid-tier gating — use this for flag mechanics; `business-growth/paywall-upgrade-cro` for the UX.
44
45## Clarify First
46
47Before designing or operating flags, confirm these inputs. If any is unknown or vague, ASK — do not assume:
48
49- [ ] **Flag type** — release, ops, experiment, or permission (sets the lifecycle, who can flip it, and auto-expiry — the root decision)
50- [ ] **Task** — design a taxonomy, simulate a rollout ramp, generate a kill-switch runbook, or audit flag debt (selects `flag_audit.py` vs `rollout_simulator.py` vs `kill_switch_runbook.py`)
51- [ ] **Blast radius / population** — user count and ramp profile, or the dependency a kill switch guards (drives `--users`/`--profile` and the runbook content)
52
53Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
54
55## Tools
56
57| Tool | Purpose | Command |
58|------|---------|---------|
59| `flag_audit.py` | Scan a codebase for flag references, age, classification, and recommended action (optionally cross-reference a control-plane export) | `python scripts/flag_audit.py --path . --format markdown` |
60| `rollout_simulator.py` | Model a rollout: per-step blast radius, time-to-detect, recommended schedule | `python scripts/rollout_simulator.py --users 500000 --profile standard` |
61| `kill_switch_runbook.py` | Generate a kill-switch runbook (default state, flip procedure, validation, escalation) | `python scripts/kill_switch_runbook.py --flag ops.recs.kill_switch --feature Recommendations --dependency recs-svc` |
62
63All scripts: standard library only, argparse CLI, JSON + human-readable output. Run `--help` for full usage.
64
65## References
66
67Load the reference that matches the task — keep this file lean and pull detail on demand:
68
69- **[references/flag-types-and-patterns.md](references/flag-types-and-patterns.md)** — the four flag types in depth, code patterns per type, evaluation-context schema, naming conventions, server-vs-client trade-offs, and storage models. Read when designing a flag system or writing the gating code.
70- **[references/operations-governance-and-workflows.md](references/operations-governance-and-workflows.md)** — the standard ramp table, blast-radius math, kill-switch design, the governance matrix + audit-log requirements, the flag-debt cleanup loop, all four end-to-end workflows, the anti-patterns list, and the tooling input/output reference. Read when running a rollout, defining governance, or executing a workflow.
71- **[references/rollout-and-kill-switch-playbook.md](references/rollout-and-kill-switch-playbook.md)** — rollout decision tree, ramp templates by change type, cohort/segment selection, kill-switch design, and monitoring/alerting hookup. Read when planning a specific ramp or wiring kill-switch alerting.
72- **[references/flag-debt-and-cleanup.md](references/flag-debt-and-cleanup.md)** — what flag debt costs, the cleanup cadence, dead-code detection, safe removal procedures, PR templates, and governance for flag count. Read when paying down stale flags.
73
74## Scope & Limitations
75
76**This skill covers:** flag taxonomy and lifecycle, rollout ramps with blast-radius math, kill-switch design and runbooks, governance/audit requirements, and flag-debt cleanup — provider-agnostic across LaunchDarkly, Statsig, Unleash, Flagsmith, ConfigCat, GrowthBook, OpenFeature, and homegrown systems.
77
78**This skill does NOT cover:** the statistical design of A/B tests (pair with `product-team/experiment-design`), the paywall/upgrade UX for entitlements (`business-growth/paywall-upgrade-cro`), or the metric instrumentation needed to make ramp decisions (`engineering/observability-designer`).
79
80## Related skills
81
82- `engineering/observability-designer` — wire the metrics needed to make ramp decisions
83- `engineering/incident-commander` — flag-based rollback during incidents
84- `engineering/chaos-engineering` — verify kill switches actually work under fault injection
85- `product-team/experiment-design` (if available) — statistical design of A/B tests behind flags
borghei