Hypothesis Design

This skill handles CF-02: Hypothesis Discipline from the release-decision framework.

Its job is to convert a goal into a testable, falsifiable statement before any implementation or measurement work begins.

When to Activate

Goal exists but no causal claim links the change to the outcome
User says "we think this will help" without explaining the mechanism
hypothesis field is empty or non-falsifiable
User is about to build without stating what they expect

On Entry — Read Current State

Use the project-sync skill's get-project command to load the current project state from the database. Check:

goal and intent — were they set by intent-shaping? If empty, go back to intent-shaping first.
hypothesis, change, variants, primaryMetric — are they already filled? If so, verify with the user whether to refine or start fresh.
stage — confirms where the project is in the loop.

This read is required. Do not rely on conversation memory alone — the database is the canonical source.

Core Template

We believe [change X] will [move metric Y in direction Z] for [audience A], because [causal reason R].

Every component is required. A hypothesis without a causal reason is a hope, not a testable claim.

Validation Questions

Check each component:

Change X — Is this specific enough to implement? Could two engineers build the same thing from this description?
Metric Y — Is this measurable? Does instrumentation exist or can it be built?
Direction Z — Is the direction stated (increase / decrease / maintain)?
Audience A — Is the target audience specific enough to be segmented in analysis?
Reason R — Is the causal mechanism explicit? "Because users will like it" is not a reason.

Decision Actions

Draft the hypothesis

Work with the user to fill all five components. Ask about missing parts one at a time.

Test for falsifiability

Ask: "Under what conditions would we conclude this hypothesis was wrong?" If the answer is "none", it is not falsifiable.

Sharpen the metric claim (optional)

The hypothesis does not need a specific number at this stage. It needs a direction. Quantitative targets belong in the evaluation plan, not the hypothesis.

Operating Rules

Do not proceed to implementation planning until all five components are present
Do not conflate the hypothesis with the success threshold (that belongs in evidence-analysis)
Hand off to reversible-exposure-control once hypothesis is confirmed

Persist State

Use the project-sync skill to sync state to the web database:

update-state <project-id> --hypothesis "We believe [change] will [move metric] for [audience] because [reason]" --change "[specific change]" --variants "[control / treatment]" --primaryMetric "[metric name]"
set-stage <project-id> hypothesis
add-activity <project-id> --type stage_update --title "Hypothesis formed"

Reference Files

references/hypothesis-template.md — full template, good/bad examples, falsifiability check, what belongs here vs. in evidence-analysis

hypothesis-design