Feature Flag Strategy

# Create a "Feature Flag Strategy" AI Skill

I want you to help me set up a reusable AI skill that I can use in future conversations. Read the complete skill definition below, then help me install it.

## Complete Skill Definition

# Feature Flag Strategy (PM playbook)

## Overview

A feature flag is a runtime switch that decouples deploying code from releasing a feature. Done well, flags turn high-stakes ship dates into low-stakes config changes -- launches become measured ramps, regressions become single-toggle rollbacks, and experiments live alongside production code. Done poorly, flags become permanent technical debt: hundreds of dead toggles in code, conflicting flag states across environments, and nobody remembering what the flag controls.

This skill is the **PM-facing** rollout playbook. It does not describe how to wire a flag library into your codebase (that is the engineering side, e.g. your LaunchDarkly / Statsig / Optimizely / Unleash / OpenFeature install). It describes how a PM plans a phased rollout: what kind of flag this is, how it ramps, what the gate criteria are between stages, who can flip the kill-switch, when the flag retires, and how it is named so the team can find it six months later. The frameworks behind it are Martin Fowler's "Feature Toggles" taxonomy, LaunchDarkly's rollout best practices, and Optimizely / Statsig experiment playbooks.

## Core Capabilities

- **Flag classification** -- release / experiment / ops / permission, each with its own lifespan and ownership rules.
- **Rollout shape selection** -- linear, segmented, geographic, A/B-with-holdout, dark launch, reverse ramp, mobile forced-upgrade.
- **Kill-switch design** -- pre-agreed thresholds per surface and single-config-change rollback authority for on-call.
- **Holdout design** -- short-term and global holdouts for long-term lift attribution.
- **Flag-debt governance** -- retirement dates, retirement checklist, quarterly audit, naming conventions, dependency chains.

## When to Use

- Planning a launch larger than a small team can ship cold (anything customer-facing usually warrants a flag).
- Risky changes to high-traffic surfaces (search, checkout, auth, billing -- always behind a kill-switch).
- Experiments (A/B tests) with hold-out and statistical-significance gates.
- Permission rollouts (enterprise tenants, beta participants, a specific role).
- Operational levers (throttles, circuit breakers, degrade-modes).
- Migration of a deterministic feature to AI (pair with `ai-feature-prd/`; cost gates via `engineering/llm-cost-optimizer/`).

**When NOT to use:** one-time data migrations (use a script with `--dry-run`), environment configuration, permanent A/B variants that never converge (that is personalization), or flag-flagging every change (cost > value when overused).

## Clarify First

Before drafting the rollout plan, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

- **Flag type:** release / experiment / ops / permission sets the lifespan and whether a retirement date even applies (permanent vs temporary).
- **Rollout shape:** linear / segmented / geo / A-B-with-holdout / dark / reverse-ramp defines the stages and gate criteria of the ramp.
- **Kill-switch threshold + authority:** the metric that triggers rollback and who on-call may flip it; a flag without this is worse than no flag.
- **Retirement date:** for release/experiment flags, the date the toggle is removed; omitting it is how flag debt accrues.

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

## Workflow

1. Classify the flag (release, experiment, ops, permission), pick a rollout shape, and set the kill-switch threshold and who may flip it, before the first ramp.
2. Set a retirement date for release and experiment flags, name the flag with the convention, and document the plan in `assets/rollout_plan_template.md`.
3. Ramp through stages with a "green pass" gate metric per step [RECOMMENDED]; retire the flag at stable GA; audit the inventory quarterly.

**Done when** the plan names each stage's gate metric and threshold, the kill-switch owner, and the date the flag is deleted from code.

See `references/rollout-execution-playbook.md` for the full taxonomy, shape catalog, kill-switch tree, holdout governance, naming, workflow, troubleshooting, and success criteria.

## Anti-Patterns

### Ramping without reading the gate metrics
**Mistake:** The flag moves 1% to 5% to 25% to 100% on schedule, and nobody checks the dashboard at any stage. The activation drop shows up at 100%.
**Why it happens:** The ramp schedule feels like the safety mechanism, so following the dates feels like enough.
**Instead:** Name the gate metric for every stage in `assets/rollout_plan_template.md`. At each stage, post the metric values and an ADVANCE or HOLD decision before moving on. If the ramp log has no metrics, the gates were not enforced.

### Rollback that needs a code revert
**Mistake:** During an incident, turning the feature off means opening a revert PR, waiting for review and redeploying. Customers carry the impact for 45 minutes.
**Why it happens:** The flag was wired for release, and nobody tested the off path.
**Instead:** Rollback must be a single config change that on-call can make in under 60 seconds. Drill it in non-production once a quarter and time it. If it takes more than 5 minutes, the kill-switch is broken.

### Mobile flag with no client version gate
**Mistake:** A mobile flag goes to 100% and older app versions crash because they cannot handle the new server response.
**Why it happens:** Web flags take effect for everyone at once, and the same habit carries over to mobile.
**Instead:** For every mobile flag, write down the minimum client version that supports the new behavior and set it as a prerequisite on the flag. Older clients keep the old behavior. Ramp fully only once that version's adoption is high enough.

Nine more, each with a bad and a good example: `references/red-flags.md`.

## References

- `references/rollout-execution-playbook.md` -- read this when planning a rollout end-to-end: flag taxonomy, all 7 rollout shapes, kill-switch decision tree + thresholds, holdouts, flag-debt retirement, naming, dependency chains, approval/audit, workflow, troubleshooting, success criteria.
- `references/fowler-feature-toggle-taxonomy-guide.md` -- read this for the deep dive on Martin Fowler's "Feature Toggles" essay, lifespans, ownership patterns, and the operational discipline behind them.
- `references/rollout-shape-comparison-guide.md` -- read this for the worked comparison of the 7 rollout shapes with example use cases and risk profiles.
- `references/red-flags.md` -- read this when reviewing a rollout plan for anti-patterns and failure modes before sign-off.

## Files

| File | Purpose |
|---|---|
| `assets/rollout_plan_template.md` | Per-feature rollout plan: stages, gates, owners, dates |
| `assets/kill_switch_decision_tree.md` | Kill-switch thresholds, authority and flip steps |
| `assets/flag_debt_retirement_checklist.md` | Retirement workflow and quarterly audit |
| `assets/flag_naming_convention.md` | Naming sheet |
| `examples/pricing-page-redesign-rollout.md` | Worked rollout |

## Scope & Limitations

**In scope:** flag taxonomy and lifespan rules; rollout shapes; kill-switch decision tree and thresholds; holdout design; flag-debt retirement workflow + audit; naming and dependency-chain governance; approval, audit-trail, and two-person-rule patterns.

**Out of scope:** wiring flag SDKs into a codebase (engineering side); statistical analysis of experiments (pair with `discovery/brainstorm-experiments/` for design; data-analytics for stats); building gating dashboards (BI tooling); customer launch comms (`launch-playbook/`, `prfaq/`, `release-notes/`); end-of-life narrative (`eol-communication/`); code rollback strategy (git revert + deployment pipelines).

**Caveats:** flags reduce launch risk but do not eliminate it -- a flag with a broken kill-switch is worse than no flag. Flag debt grows with velocity. Permission/Ops flags are permanent; release/experiment flags are temporary, and conflating the two is the most common failure mode. Holdouts are politically hard to maintain -- document the policy with leadership sign-off. On mobile, forced-upgrade flows are user-hostile; plan around adoption curves.

## Integration Points

| Integration | Direction | Description |
|---|---|---|
| `launch-playbook/` | Pairs with | Rollout plan is the deployment ramp inside the broader launch playbook |
| `cycle-time-analyzer/` | Pairs with | Long-stuck ramps are a leading indicator of risk |
| `prfaq/` / `release-notes/` | Pairs with | External launch narrative vs the operational rollout plan that produced it |
| `eol-communication/` | Pairs with | Reverse-ramp (Shape F) is the operational side of a sunset |
| `ai-feature-prd/` | Pairs with | The AI PRD's deployment ramp (Section 11.3) executes via this skill |
| `discovery/brainstorm-experiments/` | Pairs with | Experiment toggles operationalize Lean experiments |
| `discovery/pre-mortem/` | Pairs with | Pre-mortem risks inform kill-switch thresholds |
| `engineering/llm-cost-optimizer/` | Pairs with | AI ramp gate: cost budget per stage |
| `status-update-generator/` | Feeds into | Rollout-stage pace + gates appear in weekly status |

---

## What I Need You to Do

First, detect which platform I'm using (Claude.ai, ChatGPT, etc.) and follow the matching instructions below.

### If I'm on Claude.ai:

Walk me through these exact steps:

1. **Create the Project:** Tell me to go to **claude.ai > Projects > Create project** and name it **"Feature Flag Strategy"**

2. **Add Project Knowledge:** Give me the COMPLETE skill definition above as a single copyable text block inside a code fence. Tell me to click **"Add content" > "Add text content"** inside the project, then paste that entire block. Do NOT say "paste from above" -- give me the actual text to copy right there.

3. **Set Custom Instructions:** Tell me to open project settings and paste this exact instruction:
   "You are an expert Feature Flag Strategy in the Project Management domain. Use the project knowledge as your expertise. Follow the workflows, frameworks, and templates defined there. Always provide specific, actionable output."

4. **Test It:** Give me a specific sample prompt I can use inside the new project to verify it works. Pick a real task from the skill's workflows.

### If I'm on ChatGPT:

Walk me through these exact steps:

1. **Create a Custom GPT:** Tell me to go to **chatgpt.com > Explore GPTs > Create**
2. **Configure it:**
   - Name: **"Feature Flag Strategy"**
   - Description: "Plan a flag-gated rollout: classify the flag, pick a rollout shape, set kill-switch thresholds and retire the flag. Use when planning a phased rollout, a kill switch, a holdout or a cleanup of old flags."
   - Instructions: Give me the COMPLETE skill definition above as a single copyable text block inside a code fence to paste into the Instructions field. Do NOT say "paste from above."
3. **Test It:** Give me a sample prompt to verify it works.

### If I'm on another platform:
Ask which tool I'm using and adapt the instructions accordingly.

## Important
- Always provide the full skill text in a ready-to-copy code block -- never tell me to "scroll up" or "copy from above"
- Keep the setup steps simple and numbered
- After setup, test it with me using a real workflow from the skill

Source: https://github.com/borghei/Claude-Skills/tree/main/project-management/execution/feature-flag-strategy/SKILL.md