Product increment contract

# Product increment contract

## Goal

Turn one accepted solution shape plus its product, customer, usage, support, and repository evidence into a bounded product increment that an implementation team can build and verify without silently expanding the product.

The contract defines the outcome, observable behavior, scope, constraints, and acceptance boundary. It is not a roadmap, a feature wish list, or an implementation plan.

This is product shaping. Do not modify application code, tests, configuration, dependencies, generated files, or production systems. Create or update only the product artifacts named below.

Complete the analysis autonomously. Do not stop to ask clarifying questions. If the evidence does not support a bounded increment, return `HOLD` or `REVISIT SHAPE` and preserve the unknowns.

## Prerequisites

Read, in order:

* every applicable `AGENTS.md` and repository instruction file
* `docs/product/solution-shaping.md`, `docs/product/solution-shaping.yaml`, and `docs/product/solution-shaping-changelog.md`
* the upstream opportunity-prioritization, problem-definition, and discovery-synthesis artifacts referenced by that shape
* the latest product feedback, ICP, positioning, onboarding, support, retention, usage, and metric evidence available in the repository
* the current implementation, tests, schemas, public interfaces, documentation, issue records, and recent relevant history
* any existing `docs/product/increment-contract.md`, `docs/product/increment-contract.yaml`, and `docs/product/increment-contract-changelog.md`

The repository must contain an existing product or working code path to increment. If there is no implemented baseline, this series is premature; return `REVISIT SHAPE`. If the solution-shaping artifacts are absent or do not carry a `SHAPE` or `SHAPE NARROWLY` decision, return `HOLD` rather than silently selecting a solution inside this prompt.

Do not infer customer demand from code alone. Do not infer feasibility from a ticket title alone. If upstream sources conflict, name the conflict before choosing a decision.

## Evidence standard

Label every material claim with exactly one shared product label:

* `OBSERVED`: directly present in repository behavior, tests, telemetry, customer records, or other inspectable evidence
* `DERIVED`: calculated or logically concluded from cited observations; show the derivation
* `ASSUMED`: necessary but unverified; state why it is being used and how it could be tested
* `UNKNOWN`: not supported by available evidence; state what would resolve it

A request proves a request exists. It does not prove priority. A failing test proves the tested behavior fails, not that customers care. A usage count proves an event occurred only if the event definition and window are known.

Every acceptance criterion must trace to an observed product invariant, customer outcome, contractual obligation, accessibility expectation, security boundary, or explicitly labeled assumption.

## Step 1: Establish the implemented baseline

Describe the current end-to-end behavior relevant to the proposed increment:

* user, role, and job
* entry point, inputs, state transitions, outputs, and failure behavior
* product surfaces, interfaces, data, and dependencies involved
* current test coverage and observability
* known accessibility, security, privacy, performance, and reliability constraints

Cite file paths, tests, records, or measurements. Separate what the product does from what documentation claims it does.

If the baseline cannot be reproduced or understood safely, do not contract around guesswork; return `HOLD`.

## Step 2: State the product problem

First inherit the selected solution shape without broadening it: shape ID and version, essential behavior, in-scope and excluded behavior, constraints, no-gos, appetite, riskiest premises, and the increment-contract handoff. Cite each inherited clause. A material change of mechanism, user, outcome, or boundary is not contracting; return `REVISIT SHAPE`.

Write one problem statement in this form:

“For [specific user] attempting [job], [observed current behavior] causes [observable consequence]. This increment succeeds when [measurable changed behavior], without changing [protected invariant].”

Then record:

* triggering evidence and its freshness
* who experiences the problem and who does not
* frequency, severity, and business or user consequence when known
* current workaround and its cost
* why this increment is more appropriate now than no change, a process change, or a larger redesign

Do not combine unrelated problems because they touch the same screen or subsystem.

## Step 3: Define the smallest coherent increment

Specify one increment with a stable `increment_id` and:

* outcome and user-visible behavior
* included user paths, roles, data states, and platforms
* explicit non-goals and excluded adjacent requests
* protected behaviors and backward-compatibility expectations
* allowed dependencies, migrations, flags, or interface changes, if any
* product copy or documentation that must remain consistent

Create a business-rule and permission ledger with stable IDs. For each rule or permission record the actor, preconditions, allowed and forbidden action, state transition or invariant, failure behavior, evidence label, and source. Include authorization, tenancy, entitlement, ownership, approval, data-access, and retention boundaries when they are implicated. Do not hide consequential rules inside prose or a happy-path criterion.

Trace every included behavior, rule, and permission to the accepted shape. Record deliberate narrowing and confirm that it still produces a coherent outcome. Do not revive a rejected approach or move an excluded rabbit hole into scope without returning to solution shaping.

Prefer the smallest change that produces the whole contracted outcome. A smaller patch that leaves the job incomplete is not narrowness; it is partial delivery.

If the increment cannot be separated from a larger architectural or product decision, return `REVISIT SHAPE`.

## Step 4: Write verifiable acceptance criteria

Create stable criterion IDs. Each criterion must include:

* precondition and actor
* action or event
* observable result
* evidence source or label
* verification method and expected test level
* relevant failure, empty, loading, permission, and recovery state

Cover the happy path and the smallest representative set of edge cases. Include accessibility, security, privacy, performance, reliability, localization, and compatibility criteria only where the product surface or risk makes them relevant; explain any material category marked not applicable.

Every applicable business rule and permission ID must trace to at least one acceptance criterion. State the intended success measure separately from product behavior so later outcome measurement cannot mistake implementation acceptance for customer value.

Use measurable thresholds where evidence supports them. If a threshold is assumed, label it `ASSUMED` and define the observation needed to replace it.

Do not prescribe filenames, classes, framework choices, or algorithms unless an existing invariant requires them.

## Step 5: Set product quality bars

Create explicit quality-bar IDs for each materially relevant category: accessibility, security, privacy, data integrity, performance, reliability, compatibility, localization, observability, and supportability. For each, record the affected surface, current baseline when observed, release-blocking threshold or qualitative bar, evidence label, verification method, and why any category is not applicable.

An unknown baseline remains `UNKNOWN`. An assumed threshold must be labeled `ASSUMED` and may not be presented as current performance or an industry fact. Each release-blocking quality bar must trace to an acceptance criterion and later verification evidence.

## Step 6: Define release and learning boundaries

Describe, without executing:

* the smallest safe exposure or rollout boundary
* the observable signal that confirms the outcome
* health and guardrail signals that detect harm
* a rollback trigger and what user or data state must survive rollback
* any migration reversibility or compatibility requirement
* the decision window after release

Do not claim telemetry exists without tracing it to the current product. Missing instrumentation may be part of the increment only when it is necessary to verify the contracted outcome.

## Step 7: Desk-test the contract

Run these tests:

1. **One problem.** Every included behavior serves the same user outcome.
2. **Evidence.** Each material claim and criterion has one of the four labels and a source or test path.
3. **Baseline.** Current behavior is inspectable and protected invariants are named.
4. **Boundedness.** Included and excluded work can be distinguished without interpretation.
5. **Verifiability.** Every criterion can be checked before production release.
6. **Operability.** Observability, failure behavior, and rollback are proportional to risk.
7. **Quality.** Accessibility, security, privacy, performance, reliability, and compatibility were considered rather than silently omitted.
8. **No implementation capture.** The contract specifies behavior and constraints, not an invented solution architecture.

Any material failure forces `CONTRACT NARROWLY`, `HOLD`, or `REVISIT SHAPE`.

## Decision

Conclude with exactly one:

* `CONTRACT`: one coherent, evidenced increment is ready for implementation planning
* `CONTRACT NARROWLY`: only the named subset is supportable; excluded behavior remains out
* `HOLD`: prerequisites, evidence, or safe verification are missing
* `REVISIT SHAPE`: the proposed work is the wrong problem, multiple products, or cannot yet be bounded

Lead with:

“As of [date], increment [increment_id] for [user and job] changes [current behavior] to [contracted outcome], with [N] acceptance criteria and [N] unresolved unknowns; decision [CONTRACT / CONTRACT NARROWLY / HOLD / REVISIT SHAPE].”

## Deliverables

Create or update only:

### 1. `docs/product/increment-contract.md`

Lead sentence, inherited solution shape, evidence ledger, implemented baseline, problem statement, increment boundary, business rules, permissions, protected invariants, success measures, acceptance criteria, quality bars, release and learning boundaries, desk-test results, assumptions, unknowns, and sources.

### 2. `docs/product/increment-contract.yaml`

Include `version`, `status`, `as_of_date`, `decision`, `increment_id`, `solution_shape_id`, `solution_shape_version`, `user`, `job`, `problem`, `baseline`, `outcome`, `scope`, `non_goals`, `business_rules`, `permissions`, `protected_invariants`, `success_measures`, `acceptance_criteria`, `quality_bars`, `observability`, `rollout_boundary`, `rollback`, `assumptions`, `unknowns`, and `sources`.

Each acceptance criterion must have a stable ID, evidence label, and verification method. Unknown values are `null` with an explanation.

### 3. `docs/product/increment-contract-changelog.md`

Append only. Record version, date, decision, what changed in scope or criteria, and the evidence that caused the change. Never rewrite prior decisions.

Version the contract independently. Parse the YAML and confirm that the three files agree.

## Boundaries

* Do not modify product code, tests, dependencies, configuration, generated files, or lockfiles.
* Do not contact users, promise delivery, deploy, or touch production, secrets, or user data.
* Do not invent demand, usage, defects, performance, or feasibility.
* Do not hide assumptions inside acceptance criteria.
* Do not combine multiple increments to make the proposal feel substantial.
* Do not replace an observed product problem with a preferred technical project.
* Preserve unrelated work and repository history.

## Done when

* One stable increment ID, inherited solution-shape ID and version, user, job, baseline, outcome, and boundary are explicit.
* Business rules, permissions, success measures, and quality bars have stable IDs and trace into acceptance criteria.
* Acceptance criteria are independently verifiable and traceable to evidence.
* Non-goals and protected invariants prevent silent scope expansion.
* Observability, rollback, accessibility, security, privacy, performance, and reliability are addressed proportionally.
* Desk tests passed or forced a narrower or stopping decision.
* The Markdown, YAML, and append-only changelog parse and agree.