hypotheses

Invocation#

echo-cli hypotheses list --product <id> [--order rice]
echo-cli hypotheses add --product <id> --statement <text> --impact <n> --confidence <n> --ease <n> --by <name>
echo-cli hypotheses reach --id <hypothesis-id> --metric <metric-id> --days <days> --by <name>
echo-cli hypotheses link --id <hypothesis-id> --experiment <experiment-id>

Inputs and output#

list writes the product's hypotheses, highest ICE score first or, with --order rice, highest RICE first and those without a declared reach after them by ICE: id, product_id, statement, impact, confidence, ease, score (their product), reach_metric_id, reach_days, reach_set_by, reach (null until declared, else metric — the tracking metric as stored — days, since and value, the metric's value over those days counted now), rice (reach value × impact × confidence × ease, null without a reach), experiment_id, linked_at, created_by, created_at and experiment, null until linked, else the adaptive experiment as stored now with id, surface_key, status and winner_variant_key. add, reach and link write the hypothesis they queued, declared or linked.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/hypotheses with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Hypothesis queue section of the tracking screen and of Echo Desktop's GEO screen call the same operations, and echo-mcp reads the queue (echo_hypothesis_queue, with order rice) and declares reach (echo_hypothesis_reach). Impact, confidence and ease are the operator's own positive numbers on a scale they keep; the ICE score is computed on every read and never stored. reach names one of the product's tracking metrics (echo-cli tracking metrics list) and a number of days; on every list the metric's value over the last that many days is counted from the stored web and mobile events, as OKR progress is, and never stored. RICE is reach × impact × confidence ÷ effort with ease standing for the inverse of effort, so reach × impact × confidence × ease. A hypothesis is linked once, to an adaptive experiment as echo-cli experiments lists it; list reads that experiment on every call, so when it graduates its winning variant shows as the hypothesis's verdict, and while it runs its status shows with no verdict.

Refusals#

• A wrong invocation is refused before anything is sent: "hypotheses takes <every verb's usage, separated by semicolons>; got <word>", "hypotheses <verb> does not take <flag>; it takes …", "<flag> needs a value", "hypotheses <verb> needs <flag>" for each flag the verb needs, and "--impact must be a number; got <text>" (and --confidence, --ease).
• reach is refused with "--days must be a number; got <text>" before anything is sent, and Echo Web answers "reach_metric_id is required: …", "reach_days must be a positive whole number: the days over which reach is counted; got <value>" or "reach_set_by is required: …", and not found with "product <id> has no metric <id>; echo-cli tracking metrics list --product <id> lists them". list refuses "order takes rice (the queue is by ICE without it); got <value>", and fails naming the hypothesis when its reach metric was removed.
• Echo Web answers a bad request with "product_id is required: …", "statement is required: what is believed to move the product, and why", "impact must be a positive number: …; got <value>" (and confidence, ease), "id is required: …", "experiment_id is required: …" or "created_by is required: an internal caller has no signed-in user, so it names who is acting"; not found with "no product has id <id>; echo-cli products lists the ones that exist", "no hypothesis has id <id>; echo-cli hypotheses list --product <id> lists them" or "no adaptive experiment has id <id>; echo-cli experiments lists them"; and a conflict with "hypothesis <id> is already tested by experiment <id>, linked at <time>" or "hypothesis <id> was linked to another experiment while this link ran; read it with echo-cli hypotheses list". The command prints Echo Web's sentence and exits non-zero.