Product rollout planning

# Product rollout planning

## Goal

Turn a verified product increment in an existing codebase into a controlled rollout plan that limits blast radius, preserves a credible comparison, and gives a human operator explicit gates for continuing, narrowing, holding, or returning the release to delivery.

A merged change is not a rollout. A passing test suite is not evidence that production users will receive value. This prompt plans exposure; it does not create it.

This is a planning task. Do not deploy, merge, publish release notes, change feature flags, run migrations, contact users, alter production data, connect to production systems, or execute a rollback.

Complete the plan autonomously. Do not stop to ask clarifying questions. When a safe gate cannot be supported from the repository, mark the gap `UNKNOWN` and choose `HOLD` or `REVISIT RELEASE`.

## Inputs

Locate and read:

* all applicable `AGENTS.md` files
* `docs/product/release-readiness.md`, `docs/product/release-readiness.yaml`, and `docs/product/release-readiness-changelog.md`
* the approved product contract, opportunity, scope, and success criteria for this increment
* the current implementation and the exact release candidate, commit, tag, or build identifier
* acceptance, test, QA, security, privacy, accessibility, and performance evidence
* architecture decisions, dependency changes, API or schema changes, migration plans, and compatibility notes
* release, incident, rollback, backup, recovery, and feature-flag procedures
* current event definitions and the approved measurement plan
* relevant support, onboarding, adoption, retention, and product-feedback records
* the current ICP, positioning, pricing, commitments, and allowed claims from `docs/gtm/`
* contractual, regulatory, data-processing, residency, retention, deletion, and notice obligations that apply
* any existing `docs/product/rollout-plan.md`, `docs/product/rollout-plan.yaml`, and `docs/product/rollout-plan-changelog.md`

Use only artifacts available in the authorized workspace. Do not query production, inspect live customer accounts, or infer that a deployment, user cohort, telemetry stream, or approval exists because a plan mentions one.

Proceed only from an inherited `GO` or `GO NARROWLY` release-readiness decision, and never broaden its candidate or exposure boundary. An inherited `HOLD` or `ROLL BACK`, a missing readiness decision, an unidentifiable candidate, unresolved acceptance criteria, a material safety or data-integrity risk without a control, or an unexplained rollback path forces `REVISIT RELEASE` or `HOLD`; do not compensate with a smaller percentage.

## Evidence standard

Label every material claim with exactly one shared product-evidence label:

* `OBSERVED`: directly supported by an identified, authorized source
* `DERIVED`: calculated or logically produced from identified `OBSERVED` inputs, with the method shown
* `ASSUMED`: a planning premise that has not been observed and could change the decision
* `UNKNOWN`: absent, inaccessible, immature, conflicting, or not safely inferable

Do not upgrade `ASSUMED` to `OBSERVED` because a stakeholder expects it. Do not turn missing telemetry into an estimate. For every `DERIVED` number, show inputs, calculation, window, exclusions, and limitations.

The evidence ceiling for this plan is the inherited release-readiness decision and its verified candidate. A test result can support readiness for the condition tested; it cannot prove a rollout occurred, production reliability, adoption, or customer outcome.

## Step 1: Identify the release boundary

Write the immutable release identity and the smallest accurate description of the behavior change.

Record:

* product contract and decision-log IDs
* release-readiness version, decision, accepted limits, and unresolved findings
* commit, tag, build, migration, or artifact identifiers that are actually present
* changed user job, workflow, interface, data path, dependency, and operator path
* intended eligible population and explicit exclusions
* compatibility assumptions
* new data collected, transformed, exposed, retained, or deleted
* operational dependencies and failure domains
* known defects, accepted risks, and unresolved unknowns
* which acceptance and release checks passed, failed, or were not run

Do not describe roadmap behavior as included. If the repository cannot distinguish the candidate from other changes, return `REVISIT RELEASE`.

## Step 2: Classify risk and reversibility

Assess each material risk across likelihood, impact, detection time, containment, and reversibility. Include:

* loss, corruption, duplication, or unauthorized disclosure of data
* security and permission changes
* privacy, consent, data-reuse, residency, and retention effects
* billing, entitlement, contract, or pricing effects
* API, integration, migration, and backward-compatibility failure
* accessibility and usability regression
* latency, reliability, capacity, and cost regression
* support burden and operator failure
* misleading product or GTM claims
* inability to attribute an observed change to this release

Name the rollback unit and the recovery path. Distinguish code rollback, flag disablement, schema rollback, data repair, and customer remediation. Do not call a release reversible if durable data or external side effects cannot be restored.

Any credible security, privacy, legal, billing, or data-integrity issue without an approved control is a stop condition, not an experiment variable.

## Step 3: Design the exposure ladder

Plan the narrowest sequence that can test the release while protecting users. Stages may include staff-controlled verification, a named low-risk eligible cohort, a limited production cohort, and broader availability, but include a stage only when its population and purpose are supported.

For every stage specify:

* stable stage ID and purpose
* eligibility and exclusion rules based on the product job, not convenient or sensitive traits
* maximum blast radius in raw counts when a population count is observed; otherwise `UNKNOWN`
* entry requirements and named human approver
* exposure mechanism a human may use
* minimum observation window tied to product cadence and delayed effects
* primary outcome signal, guardrails, and data-quality checks
* threshold to advance, remain, narrow, pause, or recommend rollback
* monitoring owner and review time
* support and incident coverage required
* contamination or interference risks

Do not manufacture a percentage cohort when the denominator is unknown. Do not target or exclude people using protected or sensitive attributes unless there is a documented lawful, necessary, and reviewed reason.

## Step 4: Pre-register gates and stop conditions

Translate the product contract into observable rollout gates before exposure occurs.

Separate:

* release health: errors, reliability, latency, data integrity, security, cost
* adoption diagnostics: eligible, exposed, attempted, completed
* product outcome: the user or business result the increment was intended to improve
* operational guardrails: support load, manual intervention, downstream breakage

For each measure state definition, numerator, denominator, source, owner, window, cohort maturity rule, expected direction, decision threshold, and evidence label. If a threshold is not inherited from the product contract, label it `ASSUMED` and explain why it is decision-relevant.

Write immediate stop conditions separately from normal review gates. Never average away a severe security, privacy, billing, accessibility, or data-integrity event.

## Step 5: Audit operational readiness

Create a readiness ledger for:

* tested rollback and recovery procedure
* backups and migration safeguards
* telemetry definitions and data-quality ownership
* incident severity, escalation, and decision authority
* support diagnostic steps and capacity
* internal documentation and operator training
* user-facing help and release language, as drafts only
* accessibility review
* security and privacy review
* legal, contractual, and required-notice review
* GTM claim ceiling and sales/onboarding implications

Every item needs an owner, evidence, status, and blocking rule. `Someone will monitor it` is not an owner. A draft message is not sent communication.

Use customer and user data only for the purpose, population, and retention period already authorized. Minimize copied fields, prefer aggregated or de-identified planning data, do not place personal or sensitive data in repository artifacts, and flag any proposed reuse that requires consent, a contract update, legal review, or a data-protection assessment.

## Step 6: Write the human runbook

Specify the ordered actions an authorized human would take, without taking them:

* confirm release identity and approvals
* capture the pre-exposure baseline
* open the first stage
* verify exposure and instrumentation
* review stop conditions and stage gates
* record the decision and evidence
* advance, narrow, hold, or execute an approved rollback
* preserve an auditable release record

Name which roles may approve exposure, emergency pause, rollback, customer communication, and broader availability. The generated artifacts advise those people; they do not substitute for their judgment or authorization.

## Step 7: Desk-test the plan

Verify:

1. The release candidate and included behavior are unambiguous.
2. Every stage has observable entry, exit, and stop gates.
3. Cohort size and observation time match the risk and product cadence.
4. Rollback is described honestly, including irreversible effects.
5. Outcome and guardrail measures were defined before exposure.
6. Privacy, legal, security, accessibility, and support readiness have owners.
7. The plan makes no claim that a deployment, user action, or outcome occurred.
8. A human can refuse the rollout at every stage.

## Decision

Choose exactly one:

* `ROLLOUT`: the complete plan is ready for authorized human execution
* `ROLLOUT NARROWLY`: only the named limited stages are supportable; broader exposure remains gated
* `HOLD`: the candidate may be ready, but an operational, evidence, authorization, timing, or capacity prerequisite is missing
* `REVISIT RELEASE`: implementation, verification, safety, compatibility, or reversibility must return to product delivery

This decision describes plan readiness. It does not mean a rollout happened.

Lead with:

“As of [date], release candidate [identifier] for [product outcome] has planned maximum exposure [observed count or unknown], highest material risk [risk], and decision [ROLLOUT / ROLLOUT NARROWLY / HOLD / REVISIT RELEASE]. No production action was taken by this analysis.”

## Required artifacts

### 1. `docs/product/rollout-plan.md`

Lead statement, evidence labels, release boundary, risk and reversibility matrix, exposure ladder, pre-registered gates, stop conditions, readiness ledger, human runbook, desk test, decision, and handoff.

### 2. `docs/product/rollout-plan.yaml`

Include `version`, `status`, `as_of`, `decision`, `release_id`, `product_contract_id`, `included_behavior`, `eligible_population`, `exclusions`, `evidence_ceiling`, `risks`, `reversibility`, `stages`, `measures`, `stop_conditions`, `readiness`, `human_approvals`, `privacy_and_legal`, `assumptions`, `unknowns`, and `sources`.

Use `null` for unknown values with an explanation. Set `status: planned` until an authorized operator appends observed execution evidence.

### 3. `docs/product/rollout-plan-changelog.md`

Append only. Record timestamp, version, author or agent, changed claims, evidence added, decision, and reason. Never rewrite a past plan or imply an unexecuted stage occurred.

## Closed-loop handoff

Hand the approved plan and candidate boundary to the authorized release owner and to the already prepared Product adoption enablement plan. If humans later execute rollout or enablement actions, run Product rollout observation and create `docs/product/rollout-observation.md`, `docs/product/rollout-observation.yaml`, and `docs/product/rollout-observation-changelog.md` before downstream prompts call the increment released.

Pass only the approved plan, current candidate boundary, and current-product claims—not observed rollout facts—to Product adoption enablement and Full-cycle GTM before execution. After execution, only Product rollout observation may supply verified release facts. GTM may prepare support, onboarding, and positioning updates within its own authorization; it may not claim availability or outcomes from this plan.

If the decision is `REVISIT RELEASE`, return the named failed gates to product delivery. If it is `HOLD`, name the owner and evidence needed to resume. Every later outcome must pass outcome measurement: supported outcomes go directly to the product cycle decision, while mixed or unsupported outcomes go through friction diagnosis first.

## Boundaries

* Do not deploy, merge, migrate, change flags, alter data, publish, or contact anyone.
* Do not connect to or write to production systems.
* Do not invent a release, approval, cohort, user, telemetry event, incident, result, or rollback test.
* Do not use sensitive data merely because it is technically available.
* Do not present a test environment result as production behavior.
* Do not hide irreversible effects behind the word rollback.
* Do not broaden claims beyond the verified release and GTM evidence ceilings.
* Preserve uncertainty and human decision authority.

## Done when

* The inherited release-readiness decision and exact candidate boundary are explicit.
* The release boundary, risks, reversibility, stages, gates, and stop conditions are explicit.
* Every material claim uses `OBSERVED`, `DERIVED`, `ASSUMED`, or `UNKNOWN`.
* Privacy, legal, security, accessibility, support, and human approvals are addressed.
* The Markdown, YAML, and append-only changelog agree.
* The decision is one of the four allowed values and no artifact suggests execution occurred.
* The handoff closes the loop to adoption, outcome evidence, the next product cycle, and Full-cycle GTM.