Feature Flag Rollout Strategist

---
name: feature-flag-rollout-strategist
description: 'Design the ROLLOUT STRATEGY for a change behind a flag — classify the flag by purpose (release, ops/kill-switch, experiment, permission — release flags stay separate from permanent entitlements), plan progressive delivery (internal → canary/% → cohorts → GA), define sticky targeting, set guardrail metrics with auto-rollback criteria and a pre-ramp kill-switch test gate, choose the fail-safe default when the flag service is down, and manage the lifecycle so release flags are removed after GA (flag debt). Owns HOW one change is de-risked, on whatever flag system exists. Use when planning a staged rollout, a canary or percentage ramp, a kill switch, or flag cleanup. Do NOT use to design the flag system itself — store, SDK, evaluation, change audit (feature-flag-architect) — model plan/feature entitlements (plan-entitlement-architect), role permissions (authorization-matrix-designer), or design/analyze an A/B test (ab-test-designer).'
---

# Feature Flag Rollout Strategist

Terms: **GA** means general availability; **UX** means user experience.

## Purpose

Feature flags are simultaneously the best way to ship safely and the
easiest way to create a permanent mess. Done well, a change reaches 1%
of internal users, bakes against guardrail metrics, expands to cohorts,
and hits GA only after a kill-switch test has produced required evidence. Done
badly, a "temporary" release flag becomes load-bearing config three
years later, a percentage rollout flip-flops users between variants
because assignment isn't sticky, and the flag is quietly conflated with
an entitlement so turning it off removes a paying customer's feature.
This skill designs the rollout STRATEGY: the flag's real purpose,
progressive stages with advance and rollback criteria, sticky targeting,
guardrails with automatic rollback, a fail-safe default, and the
lifecycle that removes the flag when it's done. It owns how a change is
de-risked into production — not who is entitled to it.

## Use When

- Use when: planning a staged/progressive rollout — internal → canary →
  percentage ramp → cohorts → GA — for a new or risky change.
- Use when: designing guardrail metrics and automatic-rollback criteria,
  or a kill switch for a change.
- Use when: choosing targeting/segmentation for a gradual release, or the
  fail-safe default if the flag service is unavailable.
- Use when: cleaning up flag debt — deciding which flags are temporary
  release flags to remove vs long-lived operational controls.
- Do NOT use when: the question is WHO gets a feature as a matter of
  PLAN — "does the Pro plan include X", usage limits, metered quotas —
  that is `plan-entitlement-architect` (permanent entitlement, not a
  rollout).
- Do NOT use when: the question is WHO may do something as a matter of
  ROLE/permission — that is `authorization-matrix-designer`.
- Do NOT use when: the flag hosts an EXPERIMENT and the task is the
  experiment's hypothesis, sample size, or reading the result — that is
  `ab-test-designer`; this skill can carry the flag it runs on, but not
  the experiment design.
- Do NOT use when: designing the flag system itself — store, software
  development kit (SDK)/interface,
  evaluation placement, fallback mechanism, propagation, change audit →
  `feature-flag-architect`.

## Inputs to Inspect

1. The change being rolled out: its blast radius, reversibility, and what
   "bad" would look like in production (errors, latency, wrong data,
   conversion drop).
2. The flag's REAL purpose: is it a temporary release flag, a long-lived
   operational kill switch, an experiment bucket, or — a common
   mislabel — actually an entitlement/permission?
3. The available metrics: which guardrail signals exist and are trustworthy
   enough to gate/rollback on (from `observability-operator` /
   `slo-reliability-architect` outputs if present).
4. The user/segment model: how users can be targeted and bucketed, and
   whether assignment can be made sticky by a stable id.
5. The flag platform's behavior: default/fallback when the service is
   unreachable, evaluation latency, and how flags are cleaned up today
   (or whether dead flags accumulate).

## Workflow

1. **Classify the flag — this decides everything.** Release (temporary,
   removed after GA), operational/kill-switch (long-lived control),
   experiment (A/B — design goes to `ab-test-designer`), or
   entitlement/permission (PERMANENT — if so, this is the wrong skill;
   route to `plan-entitlement-architect` / `authorization-matrix-designer`).
   Misclassification is the root of most flag pathologies.
2. **Design progressive stages.** internal/dogfood → canary or small % →
   cohort expansion → GA. For each stage: the population, the bake time,
   the advance criteria (guardrails green for long enough), and the
   rollback criteria. No stage advances on vibes. If a fixed launch date
   is shorter than this evidence-backed ramp, ramp pace becomes a
   release-risk choice the owner makes; teach it before asking. Define
   *bake time* (how long a stage holds with guardrails green before it
   advances; it must exceed the metric's detection window), *cohort* (the
   population a stage exposes: a percentage of users or a named segment),
   and *guardrail threshold* (the metric value that triggers rollback,
   step 4). Options: keep the full ramp and move the date; compress the
   ramp (smaller cohorts, tighter thresholds, staffed on-call cover; bake
   time stays longer than the detection window); or meet the date for
   internal users or a limited cohort and reach GA later. For each give
   why it fits, pros and cons, and money, setup, and upkeep cost, or
   unknown (on-call cover and extra monitoring usually are until priced).
   Blast radius and reversibility (effects a flag-off cannot undo, such
   as sent messages or written data, weigh against compressing) decide
   the recommendation: if the request omits either, ask only for that one
   missing fact first and recommend nothing yet. Once both are known,
   recommend one, name the fact that would change it, then ask exactly
   one owner question. The answer shapes the plan only: it authorizes no
   flag change, and Stop Conditions still apply.
3. **Make targeting sticky.** Bucket by a stable identifier so a user
   stays in one variant across sessions and surfaces — flip-flopping is
   both a UX bug and an analytics-invalidating one. Choose low-risk
   segments first; state exclusions.
4. **Set guardrails and automatic rollback.** A SMALL set of metrics that
   must not regress (error rate, latency, a key conversion/correctness
   signal), each with a threshold that triggers rollback — automatic
   where possible. Specify the kill-switch test procedure and the evidence
   required before a rollout stage advances; do not assume a test ran.
5. **Choose the fail-safe default.** What the flag evaluates to if the
   flag service is down or slow — the SAFE state (usually "old behavior"
   for a release flag; "protective" for a kill switch). A flag that fails
   open into unfinished code is an outage waiting for a network blip.
6. **Map interactions and consistency.** Combinatorial states when
   multiple flags overlap, consistency of a user's experience across
   pages/devices, and how this change relies on the flag system's
   tenant-qualified caching of flag values (consumed from
   `feature-flag-architect`, not redesigned here). Flag the risky
   combinations.
7. **Plan the lifecycle (flag debt).** Every release flag gets an owner
   and a removal trigger (post-GA + soak). The cleanup — delete the flag
   AND the dead code path — is part of THIS plan, not a someday ticket.
   Long-lived ops flags are documented as intentional.
8. **Name boundaries and deliver.** Entitlement/permission →
   `plan-entitlement-architect` / `authorization-matrix-designer`;
   experiment design/readout → `ab-test-designer`; executing the rollout
   and flipping flags on live systems follows the repo's approval path,
   not this design skill.

Flag-type classification table, stage/advance-criteria patterns, and the
fail-safe-default guide:
[references/flag-rollout-sheet.md](references/flag-rollout-sheet.md).

## Output Format

```
ROLLOUT STRATEGY — <change>
Flag type:    release | ops/kill-switch | experiment | (entitlement → WRONG SKILL, routed)
Stages:       internal → canary/% → cohorts → GA
  per stage:  population, bake time, ADVANCE criteria (guardrails green), ROLLBACK criteria
Targeting:    sticky by <stable id>; first segments; exclusions
Guardrails:   <small metric set> each with rollback threshold; automatic where possible
Kill switch:  <mechanism>; test procedure and required evidence before ramp; change authority
              and reach bound consumed from feature-flag-architect's flag system design
Fail-safe:    flag-service-down default = <safe state> (release → old behavior)
Interactions: <risky flag combinations; cross-surface consistency; caching>
Lifecycle:    owner + removal trigger; cleanup = delete flag + dead code path
Date vs ramp: (only if a fixed date conflicts) terms; options with pros/cons and
              cost or unknown; recommendation + what would change it; one owner question
Boundaries:   entitlement → plan-entitlement-architect / authorization-matrix-designer;
              experiment → ab-test-designer; live execution → approval path; flag system → feature-flag-architect
```

## Validation Checklist

- [ ] The flag is classified by purpose; if it's really an entitlement/
      permission, it's routed out, not designed here.
- [ ] Stages have explicit populations, bake times, and BOTH advance and
      rollback criteria — no advancing on vibes.
- [ ] A fixed-date-versus-ramp conflict (if any) was taught with options,
      costs or unknowns, and a recommendation before exactly one owner
      question (a missing blast radius or reversibility fact is asked
      for first, alone); the answer authorizes no flag change.
- [ ] Targeting is sticky by a stable id; a user doesn't flip variants
      across sessions/surfaces.
- [ ] A small guardrail-metric set has rollback thresholds, automatic
      where possible, plus a kill-switch test plan and pre-ramp evidence gate.
- [ ] The fail-safe default (flag service down) is the safe state, not
      unfinished code failing open.
- [ ] Risky flag interactions and cross-surface consistency are
      addressed.
- [ ] Every release flag has an owner and a removal trigger; cleanup of
      flag AND dead code is in the plan.
- [ ] Entitlement, experiment, and live-execution concerns are handed to
      their owning skills/processes.

## Gotchas

- The most expensive flag is the "temporary" one nobody removed: it
  becomes load-bearing config, doubles the code paths under test, and
  eventually someone flips it wrong. A removal trigger at creation is the
  only reliable cure.
- A release flag and an entitlement look identical in code and are
  opposite in meaning: one is meant to be deleted, the other is
  permanent product surface. Turning off a flag that was secretly an
  entitlement removes a paying customer's feature. Classify first.
- Non-sticky percentage rollouts flip users between old and new on every
  evaluation — infuriating UX and ruined analytics. Bucket by a stable
  id, always.
- A kill switch that has never been pulled is a hypothesis, not a safety
  mechanism. Test it before you need it, under load.
- Failing OPEN (flag defaults to the new code path when the flag service
  is unreachable) turns a flag outage into a feature outage — often into
  half-built code. Release flags fail to the OLD behavior.
- Guardrails with ten metrics and no thresholds don't gate anything.
  Pick the few that mean "this is going wrong" and give each a rollback
  number.
- Overlapping flags create a combinatorial state space nobody tested;
  two independent 50% rollouts make four populations. Map the
  interactions that matter.

## Stop Conditions

- The "flag" is actually an entitlement (plan/feature gating, quotas) or
  a permission (role can/can't) → route to `plan-entitlement-architect`
  or `authorization-matrix-designer`; these are permanent models, not
  rollouts, and designing them as flags creates drift.
- The flag hosts an experiment and the ask is the experiment design or
  result readout → route to `ab-test-designer`; this skill carries the
  rollout, not the statistics.
- No trustworthy guardrail metric exists to gate/rollback on → surface
  that the rollout would be blind and get the metric wired
  (`observability-operator` *(manual-only)*) before ramping beyond a tiny canary.
- Asked to actually flip flags / execute the rollout on live production →
  decline execution; this skill designs the strategy, and live changes
  follow the repo's human-approval path.
- The request is the flag system rather than one change's rollout —
  choosing the flag store, the SDK or internal interface, where flags
  evaluate, the fallback mechanism, kill-switch propagation or the
  flag-change audit → route to `feature-flag-architect`; this skill still
  picks each flag's safe value for its rollout.

## Supporting Files

- [references/flag-rollout-sheet.md](references/flag-rollout-sheet.md) —
  the flag-type classification table, stage/advance-criteria patterns,
  guardrail selection, and the fail-safe-default guide.
- `evals/evals.json` — behavior cases including the staged rollout with
  guardrails, the sticky-bucketing fix, and the flag-vs-entitlement
  refusal.
- `evals/trigger-evals.json` — discrimination against `plan-entitlement-architect`
  and `authorization-matrix-designer` (the entitlement/permission seams),
  `ab-test-designer` (the experiment seam), and `feature-flag-architect`
  (the flag system vs one rollout, including the fail-safe value vs
  mechanism seam) — four neighbours.