Product release readiness

# Product release readiness

## Goal

Determine whether an accepted product increment is operationally, technically, and organizationally ready for a bounded release, and define the exact conditions, observation window, and rollback trigger for that release.

Release readiness is a gate, not a deployment. A product can satisfy acceptance criteria and still be unsafe to expose because migration, support, documentation, observability, capacity, security, or rollback preparation is incomplete.

This is a release audit. Do not release, deploy, merge, push, change feature flags, execute production migrations, contact users, use secrets, access real user data, or modify external systems.

Default to read-only inspection plus the audit artifacts named below. A clearly safe correction to release documentation or an isolated test-only gap may be made only when it does not alter product behavior, conceal a failed gate, or disturb unrelated work; record it explicitly and keep product changes separate.

Complete the audit autonomously. Do not stop to ask clarifying questions. When a gate cannot be proven, return `HOLD` or narrow the proposed exposure.

## Prerequisites

Read, in order:

* every applicable `AGENTS.md` and repository instruction file
* the current contract, implementation plan, delivery report, acceptance verification, YAML counterparts, and append-only changelogs
* `docs/product/adoption-enablement.md`, `docs/product/adoption-enablement.yaml`, and `docs/product/adoption-enablement-changelog.md`
* release, deployment, migration, feature-flag, rollback, incident, support, analytics, security, privacy, accessibility, and operational documentation in the repository
* the actual implementation diff, current working-tree status, dependency and schema changes, build metadata, and relevant recent history
* any existing `docs/product/release-readiness.md`, `docs/product/release-readiness.yaml`, and `docs/product/release-readiness-changelog.md`

Proceed toward `GO` only when acceptance is `ACCEPT` or `ACCEPT WITH LIMITS`. A `HOLD` or `REJECT` acceptance decision cannot be overruled by release scheduling.

When the increment affects user discovery, comprehension, onboarding, documentation, support, communication, or the path to value, require an adoption-enablement decision of `ENABLE` or `ENABLE NARROWLY` and inherit its exact limits. An enablement `HOLD` or `REVISIT PRODUCT` prevents `GO`. If enablement is genuinely not applicable, record the evidence and reason rather than omitting it.

The increment ID and artifact versions must agree. If they do not, return `HOLD` until the release candidate and evidence are identifiable.

## Evidence standard

Label every material claim with exactly one:

* `OBSERVED`: directly shown by repository state, reproducible checks, or inspectable operational artifacts
* `DERIVED`: concluded from cited observations; show the derivation
* `ASSUMED`: unverified; may support a bounded preparation step but not a material `GO` gate
* `UNKNOWN`: unresolved; state what evidence or owner action would resolve it

“It can be rolled back” is not evidence without a defined path and state boundary. “Monitoring exists” is not evidence unless the signal, owner, threshold, and response are named. A checklist item marked complete without a source remains unknown.

## Step 1: Freeze the release candidate and accepted boundary

Record:

* increment ID and exact contract, plan, delivery, and acceptance versions
* acceptance decision and any limits
* release-candidate commit, diff, artifact, or changed-file basis available locally
* proposed audience, platform, region, account type, or percentage boundary
* dependencies on other releases, schemas, services, vendors, or permissions
* unrelated working-tree changes that must remain outside the candidate

Do not expand exposure beyond an `ACCEPT WITH LIMITS` boundary. If the release candidate cannot be uniquely identified, return `HOLD`.

## Step 2: Audit technical release gates

Verify with repository-supported evidence:

* required focused, regression, static, build, packaging, and compatibility checks pass for the candidate
* dependencies and lockfiles are intentional, supported, and free of unexplained drift
* configuration has safe defaults and no embedded secrets or production-only assumptions
* schema, API, event, storage, and data-contract changes are backward compatible for the rollout and rollback window
* migrations have ordering, duration, locking, failure, retry, and reversibility considered proportionally
* assets, generated files, cache behavior, and version metadata are consistent where relevant
* feature-flag or staged-exposure mechanics exist and fail safely when the plan requires them

Do not run production migrations, contact live services, or use privileged credentials. Use static inspection, dry-run facilities that are explicitly safe, and local synthetic fixtures only.

## Step 3: Audit product quality and user readiness

Confirm that the release boundary preserves the accepted outcome and limits, including:

* user-facing copy, empty, loading, error, permission, and recovery states
* keyboard, focus, semantics, contrast, motion, screen-reader, and other applicable accessibility behavior
* authentication, authorization, input handling, sensitive-data exposure, and abuse paths
* performance and resource behavior against the accepted baseline or threshold
* reliability under retry, concurrency, duplicate events, dependency failure, and partial completion where relevant
* supported platform, browser, device, locale, and version compatibility
* user, support, operator, API, migration, and release-note documentation

Apply checks proportionally to the affected product. A category may be not applicable only with an explicit reason.

If customer communication, legal review, privacy review, or support preparation is required but not authorized or present, list the responsible role and required artifact; do not perform the external action.

## Step 4: Audit observability and response ownership

For each outcome and guardrail signal, record:

* definition and source
* baseline or honest `UNKNOWN`
* healthy range and alert or review threshold
* observation window
* owner and response time
* exact decision it changes
* privacy and retention considerations

Verify locally that intended events, logs, metrics, or traces are emitted without secrets or personal data where feasible. Do not connect dashboards or alerts to production.

If the team cannot distinguish adoption from harm during the proposed exposure window, return `HOLD` or `GO NARROWLY` with a smaller observable boundary.

## Step 5: Audit rollout and rollback

Write the proposed rollout sequence without executing it:

* pre-release checks and responsible role
* exposure stages and promotion criteria
* time between stages
* observation and support coverage at each stage
* abort thresholds
* completion and post-release review condition

Write the rollback decision separately:

* trigger and decision owner
* code, flag, configuration, schema, cache, queue, and client-version actions required
* ordering and expected recovery time
* user and data states that survive or cannot be reversed
* forward-fix conditions when rollback is less safe
* verification after rollback

Do not execute rollback against a shared or production environment. If the rollback path is materially untested or depends on unavailable access, record `UNKNOWN` and do not issue an unrestricted `GO`.

## Step 6: Audit organizational readiness

Confirm that the release has proportionate ownership for:

* release decision and execution
* monitoring and incident response
* product and engineering follow-up
* support triage and known limitations
* data, security, privacy, accessibility, or compliance review where implicated
* the post-release outcome review and contract learning decision

Do not invent people, on-call coverage, response times, or approvals. A solo team may have one owner, but the capacity and observation window must be honest.

## Step 7: Build the gate ledger

For each gate record `PASS`, `FAIL`, `NOT RUN`, `NOT VERIFIABLE`, or `NOT APPLICABLE`, with evidence, owner, and closure condition.

At minimum include:

* candidate identity
* acceptance inheritance
* test and build health
* dependency and configuration integrity
* migration and compatibility safety
* accessibility
* security and privacy
* performance and reliability
* documentation and support
* observability and ownership
* rollout and rollback
* post-release measurement

Classify unresolved findings as `BLOCKER`, `MAJOR`, `MINOR`, or `NOTE`. Do not convert a failed gate to an assumption to meet a date.

## Step 8: Desk-test the release decision

1. The exact release candidate and accepted exposure boundary are identifiable.
2. No acceptance failure is being waived by this audit.
3. Material gates have reproducible evidence and owners.
4. Accessibility, security, privacy, performance, reliability, compatibility, and migration risks are proportional and explicit.
5. Outcome and harm can be observed during the release window.
6. Rollout promotion and rollback triggers are objective enough to act on.
7. No step requires this audit to deploy, touch production, reveal secrets, or access user data.
8. Unrelated work remains outside the candidate.

## Decision

Conclude with exactly one:

* `GO`: the accepted increment is ready for its defined bounded release, with all material gates passed
* `GO NARROWLY`: only the named audience, platform, stage, or exposure is supportable; promotion requires stated evidence
* `HOLD`: one or more readiness gates are missing, failed, or not verifiable; list closure conditions
* `ROLL BACK`: observed evidence indicates the candidate or current increment should be withdrawn under the documented rollback boundary; recommend the action but do not execute it

Lead with:

“As of [date], release candidate [identifier] for increment [increment_id] has [N/N] material gates passed, [N] blocker/major findings, proposed exposure [boundary], and rollback trigger [trigger or unknown]; decision [GO / GO NARROWLY / HOLD / ROLL BACK].”

## Deliverables

Create or update only the audit artifacts and any explicitly recorded safe test or documentation repair:

### 1. `docs/product/release-readiness.md`

Lead sentence, frozen candidate, accepted boundary, technical gates, product quality, observability, rollout, rollback, organizational readiness, gate ledger, findings, safe audit repairs, desk-test results, closure conditions, and decision.

### 2. `docs/product/release-readiness.yaml`

Include `version`, `status`, `as_of_date`, `decision`, `increment_id`, `contract_version`, `plan_version`, `delivery_version`, `acceptance_version`, `adoption_enablement_version`, `adoption_enablement_decision`, `candidate`, `accepted_limits`, `enablement_limits`, `proposed_exposure`, `gates`, `quality_results`, `observability`, `rollout`, `rollback`, `owners`, `findings`, `audit_repairs`, `closure_conditions`, `assumptions`, `unknowns`, and `sources`.

Use stable gate and finding IDs. Unknown values are `null` with an explanation. A `GO NARROWLY` must encode the exact exposure limit and promotion criteria.

### 3. `docs/product/release-readiness-changelog.md`

Append only. Record version, date, candidate identifier, inherited artifact versions, decision, changed gates, and new evidence. Never overwrite a previous readiness decision; append re-evaluation.

Parse the YAML and confirm that the artifacts agree with the repository evidence and acceptance result.

## Boundaries

* Do not deploy, release, merge, push, change live flags, execute production migrations, contact users, or alter external systems.
* Do not use secrets, privileged production access, or real user data.
* Do not modify product behavior during the audit.
* Only clearly safe, isolated test or documentation gaps may be corrected, and every correction must be recorded separately.
* Do not waive acceptance failures or material gates because the change is small or scheduled.
* Do not claim monitoring, ownership, rollback, or capacity without evidence.
* Preserve unrelated and pre-existing work.

## Done when

* The exact candidate, accepted boundary, enablement decision, proposed exposure, and inherited decisions are explicit.
* Every material gate has a status, evidence, owner, and closure condition where needed.
* Accessibility, security, privacy, performance, reliability, compatibility, migration, observability, support, rollout, and rollback are addressed proportionally.
* The decision and any exposure limits follow the gate ledger.
* No production or external action occurred and product repairs remain separate.
* The Markdown, YAML, append-only changelog, acceptance evidence, and candidate diff agree.