Rollout Controls
Build the switch and the signals under terms the owner has accepted. This skill never decides the release, flips the switch in a shared environment, or expands a rollout.
When to use
- The project's release policy or instructions file requires a staged or controlled rollout for this kind of change.
- The plan or the user asks for a feature flag, kill switch, canary, or staged rollout.
release-readinessblocked this change on a missing rollout policy or on rollout signals that measure nothing the policy reads.- Skip a change nobody asked to stage.
- Skip a rewrite, migration, or other high-risk transformation:
migration-strategyowns its cutover, pause, abort, and rollback, andverification-strategyowns the checks its stages pass. Say which one owns it. A bounded feature built inside that work still comes here for its own switch.
Step 1: Find the policy, or draft one for its owner
Read the project's release or rollout policy, its instructions file, and its conventions: the flag facility, metric names, dashboards, cohort definitions. Record the document and version you read.
If a policy exists, copy its terms for this change: mechanism, target state, cohort stages, baseline source, success and failure thresholds, minimum observation, kill or rollback action, authority.
If there is no policy, or a term is unsaid, draft the missing terms from the change's risk and the project's existing telemetry, and put the draft to the release or decision owner:
Rollout terms for {{change}} — a draft; not policy until accepted Mechanism: {{flag | canary | partition | staged publication | phased rollout}} Target state: {{what full rollout looks like}} Cohorts: {{stage 1 → stage n, each with its selection rule}} Baseline: {{the signal source and window the cohorts compare against}} Success / failure thresholds: {{one line per signal: correctness, safety, latency or resources, outcome}} Minimum observation: {{duration or volume per stage}} Kill / rollback action: {{the exact action and who may take it}} Authority: {{who may expand a stage; who may abort}} 1. Accept these terms as the rollout policy for this change 2. Change a term (say which) 3. Decline — ship without a staged rollout Recommendation: 1 — {{one sentence}}.Offer option 3 only when no policy requires staging. Under a policy that does, or after a release block, drop it: shipping without the rollout is a deviation that only
release-readinessmay accept, when the release contract permits that exception, never here. Ask this and end the turn;clarifying-intentowns what closes it.If the answer is option 2, revise, keep the earlier terms visible, and present the draft again. If the answer is option 3, fill
assets/rollout-record.mdbefore stopping, with Statusdeclinedand only its Policy and Next action sections, and add the row to the decision ledger beside it (add to it, never rewrite it), naming who declined and when; this skill ends here. An unaccepted draft is not a policy: build nothing against it.
Step 2: Build the switch
- Use the flag or configuration facility the project already has. If it has none, use the smallest runtime configuration read the project already performs, and name it in the record. Add no library.
- Default it to off, or to the safe state the accepted terms name. Read the switch before the risky work starts, never after a side effect.
- List every path the change adds: request handler, background job, event consumer, scheduled work, migration step, retry, cache fill. Put the switch in front of each.
- REQUIRED SUB-SKILL: invoke
test-driven-developmentin this order. The on-state test, with the switch on, fails; then write the new path behind the switch, which stays off by default, so the project's whole test command is green when that cycle closes. Then the off-state test, under that skill's preserved-behaviour cycle: it asserts that the side effect of every path in item 3 is absent, is seen green, is watched red with the guard taken off one path at a time, and is green again with the guard back. Start one off-state test from what the on state leaves behind (a queued message, a row or cache entry in the new form, a scheduled job): the prior path must handle it. - Make turning it off change behaviour without a deploy or a restart: read the switch each time the path runs, never as a build-time constant or a value loaded once at process start. Record the exact off action.
- Write the removal follow-up: an owner, and the condition after which the switch and the prior path are deleted.
Step 3: Build the signals
- For each new path, emit the signals the accepted thresholds read. Liveness serves no threshold.
- Emit through the project's existing telemetry facility, under its naming convention. Add no vendor, library, or dashboard tool.
- Carry the switch state or cohort on every signal.
- No secret, credential, token, request body, header, query string, or
personal data in a signal's value, label, or log field. Build each metric
by
adding-observabilityStep 2's rules for labels, counters, and histograms. - REQUIRED SUB-SKILL: invoke
test-driven-developmentfor each signal: a test that fails when the signal is missing or carries the wrong state. - Confirm the baseline source exists: the prior behaviour is already measured where the thresholds compare, or the off cohort supplies it. If there is no baseline, write that in the record; do not invent a number.
Step 4: Record and hand off
Open
assets/rollout-record.mdbefore filling it, and fill every section. If the terms were drafted, add the acceptance row to the ledger beside the record: who accepted, when, and the terms they saw. Terms copied from a policy need no row.Report three lines and decide nothing:
Switch: {{name}}, default {{state}}, guards {{n}} paths, off-state test {{path}} Signals: {{n}} emitted, {{n}} thresholds served, baseline {{source | none}} Policy: {{from policy, source | accepted by whom, when}}Continue the ordinary chain to verification, review, and the branch decision unchanged. REQUIRED SUB-SKILL: at the release step, invoke
release-readinesswith the record; it binds the policy and the signals. The first flip in a shared environment, every stage expansion, and every abort run under the authority the accepted terms name, never from here.
Gotchas
- A switch read inside the new path, after the side effect it should guard, is a switch in name only — shows when the off-state test passes on the response while the job the handler enqueued still ran.
- A switch on the request path leaves the consumer, the scheduled job, and the migration step the same change added running in both states — shows when the off cohort's signals keep moving after the switch is pulled.
- A signal without the switch state blends both cohorts into one series, so the baseline is the new behaviour — shows when the record's comparison names a metric the off cohort emits under the same labels.
- A written draft reads like a policy once it sits in the record — shows when the release decision binds "the policy in the rollout record" with no acceptance row in its ledger.
- A build-time flag turns off by redeploying — shows when the record's off action is the rollback the switch was meant to avoid.
Common mistakes
- Refactoring or deleting the prior path while adding the switch, so off no longer means before: keep the prior path reachable, unchanged, until the removal follow-up runs.
- Lowering a draft threshold so the first stage can pass: thresholds are the owner's; a stage that cannot meet them is a finding for the owner.
- Flipping the switch on in a shared environment to see it work: the test suite and a local run are where it is exercised; the first shared flip is the owner's action after the release decision.