agentleFS
qyndexqyndex/claude-init/.claude/skills/flag-rollout/SKILL.md

flag-rollout

Skill2 starsChanged 5 months agoMITView on GitHub

Phased rollout discipline for production. Ship code default-OFF, ramp 1%→10%→50%→100% with monitoring windows, auto-rollback on metric breach, scheduled cleanup. The "phased delivery in prod" backbone.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Pre-check — is the target flag still mid-ramp?: Before emergency-100%, query the provider for the *target* flag's current rollout %.

    line 31
  2. Distinctive:

    If exit gate not met → wait

    line 49
  3. Distinctive:

    If exit gate met + next stage exists → ramp

    line 50
  4. Very specific:

    If at 100% for ≥ cleanup_after → invoke flag-cleanup skill

    line 56
  5. Very specific:

    If auto_rollback_threshold breached → /rollback-flag <name> immediately

    line 57
  6. Distinctive:

    When ramping, the SLO burn-rate becomes the rollback trigger.

    line 63
  7. Very specific:

    Don't ramp two related flags simultaneously: If db_flag is the foundation for api_flag, ramp db first to 100%, then start api.

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Flag Rollout

Ship code default-OFF. Ramp through cohorts. Auto-rollback on metric breach. Clean up when stable.

The ramp ritual

StageFlag valueWaitExit gate
Landdefault-OFFmergeflag exists in provider, default-OFF deployed
Internalstaff ON1-2 dayszero errors, dogfooding feedback positive
Canary1%24-48 hourserror rate ≤ baseline + 0.1pp; p95 latency within budget
10%10%48-72 hourserror rate ≤ baseline + 0.05pp; engagement metric ≥ baseline
50%50%3-7 dayssuccess metric significant (per spec's success_metric)
100%100% (default-ON in config)observationone full week without regression
Cleanupflag deletedT+cleanup_afterspec marked complete; flag removed from code

Each row's exit gate is mechanical — read from observability + flag provider, not from feel.

Emergency path — hotfixes (Round 12 D)

A hotfix is corrective, not a new capability, so it skips the gradual ramp. When a spec carries service_tier: emergency (set by the hotfix pipeline):

Pre-check — is the target flag still mid-ramp? Before emergency-100%, query the provider for the target flag's current rollout %. Two cases:

  • Target is at 100% (or unflagged baseline code). The failure is live for everyone → emergency deploy to 100% immediately. This is the normal hotfix case.
  • Target is a NEW-feature flag still mid-ramp (< 100%, e.g. the bug was found in the 10% canary). Do NOT jump to 100%. Deploy the fix to the current ramp cohort only (match the present %), keep auto_rollback ON, and let the normal ramp resume once the fix is confirmed. Promoting an unvalidated feature to everyone under cover of a "hotfix" defeats the ramp's blast-radius limit — you'd be exposing the whole feature to 100% of users, not just fixing the bug for the cohort already seeing it.
StageFlag valueWaitExit gate
Emergency deploy100% if target already at 100%, else current ramp %nonefix merged + evidence bundle PASS
Watchunchanged from deploy30-min observationauto_rollback STAYS ON — slo.yml thresholds (error_rate ≥1%/5m, p95 ≥2x/10m) are the safety net that replaces the gradual ramp

The gradual ramp exists to limit blast radius of new behavior. A hotfix's job is to reduce an already-live failure, so waiting at 1% would prolong the incident — but only for behavior that is already at that exposure. A fix for a feature still at 10% stays at 10%. The auto-rollback guardrail is what keeps emergency-100% safe: if the "fix" makes things worse, the SLO breach reverts it within minutes. When the emergency deploy succeeds, fire repository_dispatch: flag-shipped → the hotfix issue moves to SHIPPED (same as a normal flag at 100%).

Process

  1. Read spec's ## Rollout section — flag.name, flag.type, default, success_metric, auto_rollback_threshold, cleanup_after.
  2. Verify flag exists in the flag-provider (OpenFeature / LaunchDarkly / PostHog / Unleash). Create if missing.
  3. Check current stage — query provider for current rollout %.
  4. Decide next action:
    • If exit gate not met → wait
    • If exit gate met + next stage exists → ramp
    • When the flag reaches 100% → mark the spec issue SHIPPED (Round 11 C). Fire a repository_dispatch so issue-lifecycle.yml moves the board:
      gh api repos/:owner/:repo/dispatches -f event_type=flag-shipped \
        -F client_payload[issue_number]="$(awk '/^github_issue:/{print $2}' specs/active/<spec-id>*.md)"
    • If at 100% for ≥ cleanup_after → invoke flag-cleanup skill
    • If auto_rollback_threshold breached → /rollback-flag <name> immediately
  5. Document the decision in .claude/memory/playbooks/flag-rollout.md or per-flag log.
  6. Schedule next check (cron or scheduled-task) at the wait-window for this stage.

Auto-rollback discipline

When ramping, the SLO burn-rate becomes the rollback trigger. Define in the spec:

auto_rollback_threshold:
  error_rate: ">= 1% for 5 minutes"
  p95_latency_increase: ">= 2x baseline for 10 minutes"
  custom: "checkout_failure_rate >= 0.5%"

The release agent's post-deploy watch monitors these. If breached:

  1. Flip flag to 0% (rollback-flag skill)
  2. Open incident (/incident-start)
  3. Post to Slack / page on-call
  4. Don't revert code — flag flip is sufficient and faster

Hard rules

  • Default-OFF unless proven otherwise. Even for "small" changes. Costs nothing; saves everything.
  • Don't skip stages. No "1% → 100%" leaps. Each stage is its own learning.
  • Wait the window. Bugs surface after time, not after request count. A 24h window is a 24h window even if 1% is silent.
  • Cleanup is part of done. A 100% flag still in the codebase is debt. Schedule cleanup at cleanup_after.
  • Don't ramp two related flags simultaneously. If db_flag is the foundation for api_flag, ramp db first to 100%, then start api.

References

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.