Standard Operating Procedure: Hypothesis-Driven Development

Owned by agent-prd. Loaded by grilling, user stories, spec, telemetry, release, and prune.

Use this when shipping a new capability whose value is unproven. Do not use this for bugs — that is hypothesis-driven-debug.md.

Align with CODING_PHILOSOPHY.md §4 (minimal change): cheapest experiment first; flag as a delivery port, not as the user want.

1. Contract vs bet

Kind	Meaning	Delivery
Contract	Settled obligation. Failure is a defect.	Ship. Flag only if ops needs a kill switch.
Bet	Belief about user or system outcome. Failure is learning.	Cheapest experiment. Usually a feature flag default off.

If the idea is still mushy, grill first (agent-grilling). Do not write Gherkin until the kind is named.

Fill before stories or spec. Template: templates/prd.md.

Field	Required
Problem	Who hurts, and how we know
Belief	If we do X for Y, Z will happen
Leading indicator	One measurable signal (not vanity)
Timebox	When we decide (date or event)
Kill criteria	What falsifies the belief
Experiment	Cheapest test (flag, preview, fake door, spike)
Flag	Name, default, audience, owner, expiry — or N/A with reason

Cap at one leading indicator per bet. Park extra metrics.

A flag is a delivery port, not a story want. Do not write I want a feature flag.

Use a flag when the slice is a bet, needs a production audience, or needs an operator kill switch.

Skip a flag when the change is a contract, fully reversible in one deploy, or the experiment is a throwaway prototype with no production path.

State	User-visible behavior	Tests
Flag off (default for bets)	Prior path; no new obligation	Functional catalog for the safe path
Flag on	New path for the named audience	Functional + XFN apply rows for the new surface
Operator kills	Immediate return to off	Spec scenario; rollback note at release

Record in story Notes (not Story/AC): flag name, default, audience, owner, expiry. Spec Gherkin covers off, on, and kill.

Do not leave flags with no expiry. Confirmed bets default on then prune the flag. Killed bets stay off then prune the slice.

Grill — Frontier includes contract vs bet, metric, timebox, kill criteria, cheapest experiment.
PRD — agent-prd writes the bet card. Skip for tiny contracts.
Stories — agent-user-stories: INVEST + Hypothesis block; flag details in Notes.
Spec — agent-spec: Gherkin for off/on/kill; one telemetry event that can falsify the belief.
Ship — agent-release: flag, default, expiry, rollback.
Measure — agent-telemetry: the leading indicator, not generic logs.
Close — After the timebox: confirmed → default on + prune flag; killed → flag off + prune slice (agent-prune). Next story records the learning.