Purpose: a lightweight, machine-reviewable contract connecting product intent, implementation, verification, and release. Use the smallest subset proportional to the risk of the change.

This template is designed for a story, feature, migration, or bounded platform change. It is not a replacement for a PRD or ADR. Link those artifacts when they exist and use this packet to make the current delivery decision explicit.

Contract header

Field Value
Contract ID stable id
Version version or last-updated timestamp
Status discovery / review / ready / implementation / verification / released / outcome-checked
Outcome owner one named person
Technical owner one named person
Delivery team team
Risk class low / medium / high / critical
Target window date or release train
Linked PRD / ADR / incident links

1. Intent and outcome

Problem or signal

What triggered the work? Link the customer signal, operational problem, incident, regulatory need, or product hypothesis.

<problem statement>

Outcome hypothesis

If we <change>, then <observable outcome> for <actor/system> will improve,
        as measured by <signal> within <time boundary>.

Non-goals

  • <explicitly excluded outcome or scope>

2. Functional contract

Required behavior

  1. <observable behavior>
  2. <observable behavior>

Failure behavior

Condition Expected behavior User/operator signal
<dependency unavailable> <fail closed / retry / degrade> <response, event, alert>
<invalid input> <reject or normalize> <response>

Acceptance examples

Given <initial state>
        When <action>
        Then <observable result>
        And <required evidence>

Include at least one success case, one permission or validation failure, and one dependency-failure case when relevant.

3. Non-functional contract

Complete only relevant rows. Replace vague words such as "fast" or "secure" with a boundary or a linked standard.

Dimension Constraint Verification
Latency <percentile and budget> <test/dashboard>
Capacity <expected and peak load> <load evidence>
Availability <required behavior during failure> <fault test/runbook>
Security <identity, authorization, data boundary> <review/scans/tests>
Privacy <data classification and retention> <review/evidence>
Compatibility <API/event/schema requirement> <contract test>
Operability <logs, metrics, traces, alerts> <dashboard/query/runbook>

4. Interfaces and dependencies

Dependency or interface Owner Contract/version Change required Failure mode
<service, event, schema, vendor> <owner> <link/version> yes/no <effect>

State ordering, idempotency, retry, timeout, and backward-compatibility expectations explicitly when the change crosses a service boundary.

5. Delivery plan

Change set

  • <repository/component and intended change>

Migration or data handling

<forward migration, compatibility window, data validation, cleanup>

Rollout

<feature flag, cohort, canary, sequence, observation period>

Rollback

<trigger, authority, steps, data implications, maximum safe rollback time>

6. Human-agent decision map

Stage Agent may Agent must not Human decision owner Required evidence
Discovery <search, summarize, list gaps> <choose outcome> <name/role> <brief>
Ready review <check fields and consistency> <approve exception> <name/role> <findings>
Implementation <edit, test within scope> <expand scope silently> <name/role> <change and test log>
Verification <run checks, assemble bundle> <self-approve high risk> <name/role> <evidence bundle>
Release <prepare, monitor, recommend> <release beyond permission> <name/role> <approval and rollout state>

7. Evidence bundle

Required before Definition of Done:

  • [ ] Contract version linked to the change.
  • [ ] Functional acceptance cases executed.
  • [ ] Relevant NFR checks completed.
  • [ ] Interface/contract compatibility verified.
  • [ ] Code and architecture ownership reviews complete.
  • [ ] Security/privacy review complete or explicitly not applicable.
  • [ ] Logs, metrics, traces, alerts, and dashboard links present as required.
  • [ ] Migration and rollback exercised or reviewed.
  • [ ] Documentation and runbook updated.
  • [ ] Known exceptions recorded with owner and follow-up date.
  • [ ] Release observation window and outcome check scheduled.

8. Exceptions and risk acceptance

Missing condition or accepted risk Reason Compensating control Owner Expires/follow-up
<item> <why ship now> <temporary protection> <one person> <date>

An agent may identify or draft an exception. A named human owner accepts it.

9. Outcome check

Complete after the agreed observation window.

Question Evidence
Did the intended outcome change? <metric, feedback, operational signal>
Did risk or operating cost move elsewhere? <incidents, queue time, support load>
What should be retained as a reusable pattern? <template, rule, test, runbook>
What follow-up work is required? <owned items>

State-transition checks

Discovery → Review

  • [ ] Problem, outcome owner, outcome hypothesis, and non-goals exist.
  • [ ] Material stakeholders and dependencies are identified.

Review → Ready

  • [ ] Functional and relevant non-functional requirements are testable.
  • [ ] Interfaces, failure behavior, evidence, rollout, and rollback are explicit.
  • [ ] Agent permission boundaries and mandatory human decisions are recorded.

Implementation → Verification

  • [ ] Scope changes are reflected in a new contract version.
  • [ ] Proposed change and machine-generated artifacts are attributable.
  • [ ] Required checks have produced inspectable evidence.

Verification → Released

  • [ ] Reviewer and release owner accepted the evidence and unresolved risk.
  • [ ] Operational monitoring and rollback authority are active.

Released → Outcome checked

  • [ ] The outcome was evaluated within the declared measurement boundary.
  • [ ] Exceptions and follow-up items have owners and dates.
  • [ ] Reusable learning was added to the relevant standard or pattern library.