# Product Gap Readiness Gate

Status: active
Owner: Product / Design / Engineering / Ops

## Purpose

Prevent UAT from becoming the first place where the team discovers missing
product workflows.

Before implementation starts for a user/admin/operator workflow, the team must
prove that the product path is complete enough to build and test. This gate
turns likely UAT misses into explicit design, contract, runtime, environment,
or accepted-gap work before broad UAT begins.

## When This Gate Applies

Apply this gate to:

- new product routes;
- major page refactors;
- launch, setup, recovery, cleanup, or multi-step workflows;
- any workflow that depends on credentials, service accounts, storage, provider
  capacity, app artifacts, scheduler controllers, external app routes, or
  environment configuration;
- any API/CLI/SDK feature that has a browser/product counterpart.

Small copy-only, styling-only, or internal implementation changes can skip this
gate only when they do not alter workflow behavior, dependency creation,
permissions, cleanup, or recovery.

## Required Product Gap Register

Each in-scope workflow must have a product gap register row before feature code
starts. The row can live in the feature spec, coverage matrix, or a dated
operations/product document, but it must be linked from the task or PR.

| Field | Required answer |
|---|---|
| Persona | End user, tenant admin, project admin, platform operator, support, finance, or developer. |
| Workflow intent | The real-world task the persona is trying to complete. |
| Canonical entry point | Product navigation, command, API, CLI, or SDK entry where the persona naturally starts. |
| Empty-state dependency | Missing credential, service account, storage, compute target, provider capacity, scheduler controller, app artifact, route, or none. |
| In-place recovery | How the user creates, selects, repairs, or requests the dependency without losing their current workflow draft. |
| Decision context | Cost, capacity, ownership, policy, role, blast radius, risk, or expected wait time needed before action. |
| Success signal | Product state plus app/API/CLI/SDK/audit/task/metric/evidence proof. |
| Cleanup path | Release, archive, delete, disable, revoke, or quarantine path for disposable resources. |
| Expected blocked states | What blocked/error states should look like and which layer owns each. |
| Environment lane | Demo, dev, kind, local, provider-specific, or all. |
| Status | `ready_for_dev`, `ready_for_uat`, `needs_design`, `needs_api_contract`, `needs_runtime_fix`, `needs_env_fix`, `accepted_gap`, or `blocked`. |

Implementation can begin only for rows marked `ready_for_dev` or
`accepted_gap`.

## Definition Of Ready For Development

A workflow row is `ready_for_dev` only when:

- the persona and canonical entry point are clear;
- the route/page family and navigation fit are documented;
- every primary action maps to a contract, command, or explicit runtime
  operation;
- empty, loading, success, restricted, error, delayed, and cleanup states are
  known;
- every required dependency has an in-product create/select/recover path or an
  accepted exception;
- role boundaries are explicit, especially tenant-admin versus project-admin;
- failure ownership is classified by layer;
- a focused proof plan exists for the smallest verification after
  implementation.

If any item is unknown, the row is not ready for development. Do design,
contract, runtime, or environment work first.

## Owning-Layer Classification

Use these owners when classifying gaps:

| Owner | Meaning |
|---|---|
| `needs_design` | The workflow, copy, IA, page family, role behavior, or recovery path is unclear. |
| `needs_api_contract` | The product needs a read/write surface, field, event, or error contract before implementation. |
| `needs_runtime_fix` | Worker, controller, provider, app runtime, scheduler, route, or auth behavior must change. |
| `needs_env_fix` | Environment profile, seed data, secret, capacity, DNS/proxy, or deploy drift blocks proof. |
| `ready_for_uat` | Design, contract, implementation, focused proof, and cleanup/recovery posture are complete enough for broad UAT. |
| `accepted_gap` | The gap is known, documented, owned, and explicitly not blocking the current release slice. |
| `blocked` | The team cannot proceed safely until an external decision or dependency changes. |

Do not relabel a product gap as a test-harness issue when the test exposes a
missing persona-complete workflow.

## Design And Development Flow

Use this sequence for each feature slice:

1. **Persona sweep**: identify the affected personas and workflows.
2. **Gap register**: create/update rows using the required fields above.
3. **Design/contract pass**: close `needs_design` and `needs_api_contract`
   before feature code.
4. **Implementation**: build only rows that are `ready_for_dev` or an accepted
   gap's scoped supporting work.
5. **Focused proof**: run the smallest browser/API/CLI/SDK/runtime proof for
   the changed row.
6. **Regression pack update**: add or update the workflow regression pack when
   the workflow is reusable or release-critical.
7. **Broad UAT**: run broad UAT only when in-scope rows are `ready_for_uat` or
   `accepted_gap`.

## Review Checklist

Reviewers should block a PR when:

- a user-visible workflow has no product gap register row;
- a launch/setup flow relies only on seeded data;
- a missing dependency sends the user away without preserving the draft or
  giving a return path;
- API/CLI/SDK support exists but the browser/product path is missing without an
  accepted gap;
- a new long-running wait loop has no fast-fail preflight, owner, and recovery
  path;
- a privileged action lacks audit/evidence visibility;
- cleanup, release, revoke, or decommission behavior is missing for disposable
  resources.

## Relation To UAT

This gate is the upstream input to:

- `doc/governance/Persona_Journey_UAT_Model_v1.md`
- `doc/operations/Demo_UAT_Package_v1.md`
- `doc/operations/Demo_UAT_Retrospective_2026-06-01.md`

The UAT package validates the rows. It should not be the first tool that
discovers them.