
Define Hypothesis
- 538 installs
- 518 repo stars
- Updated August 4, 2026
- product-on-purpose/pm-skills
define-hypothesis is a product-management agent skill that turns assumptions into testable hypothesis statements with metrics and validation plans for developers and PMs scoping experiments before building features.
About
define-hypothesis is a pm-skills agent skill from product-on-purpose/pm-skills that structures testable product hypotheses before engineering investment. Invoked as /pm-skills:define-hypothesis, it walks through belief articulation, target user segments, expected outcomes, primary and guardrail metrics, validation approach, and documented risks. Developers and PMs reach for define-hypothesis after a problem statement and before PRDs, solution briefs, or experiment-design skills in the pm-skills recipe chains. Output follows the template: We believe that [action] for [user] will [outcome] as measured by [metric], plus validation and assumption sections. The skill prevents shipping features on untested beliefs by making success criteria explicit and shared.
- define-hypothesis
- AI & Agent Building
- AI-coding skill
Define Hypothesis by the numbers
- 538 all-time installs (skills.sh)
- +30 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #1,695 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/product-on-purpose/pm-skills --skill define-hypothesisAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 538 |
|---|---|
| repo stars | ★ 518 |
| Last updated | August 4, 2026 |
| Repository | product-on-purpose/pm-skills ↗ |
How do you write a testable product hypothesis with metrics?
Helps with ai & agent building tasks.
Who is it for?
Engineers and PMs moving from problem statements to experiments who need explicit, measurable beliefs before solution or PRD work.
Skip if: Teams already past validation with approved PRDs, pure technical implementation tasks, or problems lacking a defined user segment.
When should I use this skill?
User asks to define a hypothesis, test an assumption, set experiment metrics, or chain from a problem statement before building.
What you get
Structured hypothesis statement, target user segment, primary and guardrail metrics, validation plan, and documented risks and assumptions.
- Hypothesis statement document
- Success and guardrail metrics
- Validation approach and risk notes
Files
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
Hypothesis
A hypothesis is a testable prediction about how a change will affect user behavior or business outcomes. It transforms assumptions into explicit statements that can be validated or invalidated through experimentation. Well-formed hypotheses prevent teams from building features based on untested beliefs and create shared understanding of what success looks like.
When to Use
- After problem framing, before committing to a solution
- When designing experiments or A/B tests
- When team members have differing assumptions about user behavior
- Before investing significant engineering resources in a feature
- When pivoting direction and need to validate the new approach
When NOT to Use
- You are ready to design the actual A/B test (variants, sample size, duration) -> use
measure-experiment-design; this skill frames what to test, not how - The problem itself is still unframed -> use
define-problem-statementfirst - You want to organize many assumptions and ideas into a discovery structure -> use
define-opportunity-tree - The team needs the full business-model picture, not one testable claim -> use
foundation-lean-canvas
Instructions
When asked to create a hypothesis, follow these steps:
1. State the Belief Articulate what you believe will happen. Use the structured format: "We believe that [action/change] for [target user] will [expected outcome]." Be specific about the intervention - vague hypotheses can't be tested.
2. Identify the Target User Define who this hypothesis applies to. A hypothesis about "users" is too broad. Specify the segment: new users in their first week, power users with 10+ sessions, churned users returning, etc.
3. Define the Expected Outcome What behavior change or result do you expect? Frame it in terms of user actions (complete onboarding, make a purchase, return within 7 days) rather than internal metrics when possible.
4. Set Success Metrics Choose a primary metric that directly measures the expected outcome. Include secondary metrics that provide context and guardrail metrics that ensure you're not causing harm elsewhere.
5. Describe Validation Approach How will you test this hypothesis? A/B test, user interviews, prototype testing, cohort analysis? Be specific about sample size, duration, and statistical requirements.
6. Document Risks and Assumptions What could invalidate this hypothesis beyond the test results? What are you assuming to be true that you haven't validated?
Output Format
Use the template in references/TEMPLATE.md to structure the output. A complete hypothesis document fills every template section: Hypothesis Statement; Background & Rationale; Target User Segment; Success Metrics; Validation Approach; Risks & Assumptions; and Timeline.
Quality Checklist
Before finalizing, verify:
- [ ] Hypothesis is falsifiable (possible to prove wrong)
- [ ] Success metric has a specific numeric target
- [ ] Target user segment is clearly defined
- [ ] Validation approach is practical and time-bound
- [ ] Pass/fail criteria are unambiguous
- [ ] Hypothesis doesn't assume the solution works
Examples
See references/EXAMPLE.md for a completed example.
{
"schema": 1,
"skill": "define-hypothesis",
"runs_per_query": 3,
"trigger_threshold": 0.5,
"queries": [
{
"q": "Help me write a testable hypothesis for why onboarding completion is low",
"expect": "trigger",
"split": "train"
},
{
"q": "We believe shortening signup will boost activation; turn that hunch into a falsifiable statement with success metrics",
"expect": "trigger",
"split": "train"
},
{
"q": "The team disagrees about whether power users actually want dark mode; frame the assumption so we can test it",
"expect": "trigger",
"split": "train",
"notes": "Intent-only phrasing, no hypothesis keyword"
},
{
"q": "Before we invest a quarter building the recommendation engine, what exactly are we betting is true?",
"expect": "trigger",
"split": "train",
"notes": "Intent-only phrasing"
},
{
"q": "Draft a hypothesis statement with primary and guardrail metrics for the new pricing page",
"expect": "trigger",
"split": "train"
},
{
"q": "We are pivoting to SMB customers; help articulate what success looks like so we can validate the new direction",
"expect": "trigger",
"split": "train"
},
{
"q": "Form a clear assumption to test about why trial users churn in their first week",
"expect": "trigger",
"split": "validation"
},
{
"q": "Write the We believe that X for Y will Z statement for the referral incentive idea",
"expect": "trigger",
"split": "validation"
},
{
"q": "I need to align the team on what we expect this notification change to do before anyone designs a test",
"expect": "trigger",
"split": "validation",
"notes": "Intent-only phrasing; explicitly upstream of test design"
},
{
"q": "Turn this problem statement about cart abandonment into a testable prediction with a numeric target",
"expect": "trigger",
"split": "validation"
},
{
"q": "Design the A/B test for our checkout hypothesis: variants, sample size, and duration",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "measure-experiment-design",
"notes": "Hypothesis exists; designing the test itself is the partner's job"
},
{
"q": "Plan the experiment targeting and traffic split to validate the onboarding change we framed last week",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "measure-experiment-design",
"notes": "How to test, not what to test"
},
{
"q": "We already know what we believe; now calculate how many users per variant and how long to run the test",
"expect": "no-trigger",
"split": "validation",
"near_miss_of": "measure-experiment-design",
"notes": "Sample size and duration are experiment design parameters"
},
{
"q": "Analyze the results of the completed pricing experiment and tell me whether it won",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "measure-experiment-results"
},
{
"q": "Frame the problem statement for declining engagement before we jump to solutions",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "define-problem-statement",
"notes": "Problem still unframed; that comes before any hypothesis"
},
{
"q": "Organize all our assumptions and ideas about retention into an opportunity solution tree",
"expect": "no-trigger",
"split": "validation",
"near_miss_of": "define-opportunity-tree",
"notes": "Many assumptions in a discovery structure, not one testable claim"
},
{
"q": "Sketch the full business model for this product idea on a lean canvas",
"expect": "no-trigger",
"split": "train",
"near_miss_of": "foundation-lean-canvas"
},
{
"q": "Why does my React component re-render twice in strict mode?",
"expect": "no-trigger",
"split": "train",
"notes": "Unrelated engineering ask"
},
{
"q": "Write a SQL window function to compute 7 day rolling retention",
"expect": "no-trigger",
"split": "validation",
"notes": "Unrelated"
},
{
"q": "Help me plan a surprise anniversary dinner",
"expect": "no-trigger",
"split": "validation",
"notes": "Unrelated"
}
]
}
define-hypothesis - Version History
| Version | Date | Release | Effort | Type | Summary |
|---|---|---|---|---|---|
| 2.1.0 | 2026-06-10 | v2.26.0 | F-12-batch-2 | minor | Quality convergence: When NOT to Use + output-contract enumeration (F-12 Batch 2) |
| 2.0.1 | 2026-06-10 | v2.26.0 | F-12-batch-0 | patch | Description rewrite for trigger accuracy (boundary disambiguation; 2026-06-09 audit, v2.26.0 Batch 0) |
| 2.0.0 | 2026-01-26 | - | - | baseline | Prior published version |
2.1.0 (2026-06-10)
Quality-convergence minor (F-12 Batch 2): added a "When NOT to Use" section with boundary pointers to neighboring skills, and the Output Format now enumerates the template sections a complete artifact fills. No template or example changes.
2.0.1 (2026-06-10)
Description-only patch (F-12 Batch 0, from the 2026-06-09 repo audit): the trigger-surface description was rewritten to disambiguate collision pairs with an explicit boundary pointer to the sibling skill. No body, template, or behavior changes.
2.0.0 (2026-01-26)
Baseline row for the prior published version; see git history for its changes.
Hypothesis: Simplified Onboarding Flow
Hypothesis Statement
We believe that reducing the onboarding flow from 7 steps to 3 essential steps
for new users signing up for a free trial
will increase onboarding completion rate
as measured by percentage of users who complete all onboarding steps within their first session
Background & Rationale
Problem Context
Our SaaS product has a 34% onboarding completion rate - meaning 66% of new signups never finish setup and experience the core value proposition. User research indicates the current 7-step onboarding feels overwhelming, with significant drop-off occurring at steps 4 and 5 (team invitation and integration setup). Users who don't complete onboarding are 4x more likely to churn within 14 days.
Supporting Evidence
- Session recordings show users hesitating and abandoning at the team invitation step
- Support tickets frequently ask "Can I skip some of these steps?"
- Competitor analysis shows market leaders use 3-4 step onboarding flows
- Exit survey data: 42% of churned users cite "too complicated to get started"
- Hotjar heatmaps show users scrolling to find a "skip" button that doesn't exist
Alternative Hypotheses Considered
- Progress indicators: Adding a progress bar might reduce anxiety without changing steps - rejected because underlying issue is step count, not visibility
- Tooltips/guidance: More help content might reduce confusion - rejected because it adds more cognitive load
- Optional steps: Making steps skippable might work - considered as fallback if simplification fails
Target User Segment
Definition
New users who:
- Sign up for a free trial (not paid conversion from trial)
- Are the first user from their organization (not invited team members)
- Access the product via web (not mobile app)
Segment Size
- 12,400 new trial signups per month meeting these criteria
- 8,200 (66%) currently fail to complete onboarding
Current Behavior
- Average time to complete current onboarding: 18 minutes
- Step 1-3 completion: 78%
- Step 4 (team invitation) completion: 52%
- Step 5 (integration) completion: 41%
- Full completion (all 7 steps): 34%
- Users who complete onboarding activate core feature within 24h: 89%
Success Metrics
Primary Metric
| Metric | Current Baseline | Target | Minimum Detectable Effect |
|---|---|---|---|
| Onboarding completion rate | 34% | 50% | 10% relative lift |
Secondary Metrics
| Metric | Current Baseline | Expected Direction |
|---|---|---|
| Time to complete onboarding | 18 min | Decrease to <8 min |
| Day-1 core feature activation | 30% | Increase |
| Support tickets (first 24h) | 8.2% of users | Decrease |
| User satisfaction (post-onboarding) | 3.2/5 | Increase |
Guardrail Metrics
| Metric | Current Value | Acceptable Range |
|---|---|---|
| 14-day trial-to-paid conversion | 12% | No decrease >5% relative |
| Team invitation rate (within 7 days) | 23% | No decrease >10% relative |
| Integration connection rate (within 7 days) | 31% | No decrease >10% relative |
Validation Approach
Method
A/B test with 50/50 traffic split between:
- Control: Current 7-step onboarding flow
- Treatment: New 3-step onboarding (account basics, workspace setup, first task creation)
Deferred steps (team invitation, integrations) will be prompted via in-app messaging after initial activation.
Sample Size & Duration
- Sample size: 3,000 users per variant (6,000 total)
- Duration: 14 days of enrollment + 7 days observation window
- Traffic allocation: 50% control / 50% treatment
- Statistical significance: 95% confidence level
- Statistical power: 80%
Pass/Fail Criteria
- Validated if: Onboarding completion increases by ≥10% relative (34% → 37.4%+) with 95% confidence AND guardrail metrics stay within acceptable range
- Invalidated if: Onboarding completion shows no significant change or decreases, OR guardrail metrics breach acceptable range
- Inconclusive if: Results don't reach statistical significance within test window - extend test or increase sample
Risks & Assumptions
Key Assumptions
- Users who complete a shorter onboarding will still discover team/integration features later
- The 3 essential steps are sufficient to demonstrate core product value
- In-app prompts can effectively drive deferred actions
- Onboarding completion is a leading indicator of retention (not just correlated)
Risks
- Feature discovery risk: Users might never set up teams/integrations if not prompted during onboarding
- Segment spillover: Results might not generalize to invited users or mobile signups
- Novelty effect: Initial lift might fade as users become accustomed to flow
- Selection bias: Users who would have completed 7-step flow might be different from marginal completers
Timeline
| Phase | Dates | Duration |
|---|---|---|
| Setup & instrumentation | Jan 15-17, 2026 | 3 days |
| Test running | Jan 18-31, 2026 | 14 days |
| Observation window | Feb 1-7, 2026 | 7 days |
| Analysis | Feb 8-10, 2026 | 3 days |
| Decision | Feb 11, 2026 | - |
Hypothesis: [Brief Title]
Hypothesis Statement
We believe that [specific action or change]
for [target user segment]
will [expected outcome/behavior change]
as measured by [primary success metric]
Background & Rationale
Problem Context
<!-- What problem is this hypothesis attempting to solve? Link to problem statement if available. -->
[Problem context]
Supporting Evidence
<!-- What data, research, or observations led to this hypothesis? -->
[Evidence that supports this belief]
Alternative Hypotheses Considered
<!-- What other explanations or approaches did you consider? -->
[Alternative approaches]
Target User Segment
Definition
<!-- Specific criteria that define this user segment -->
[User segment definition]
Segment Size
<!-- How many users fall into this segment? -->
[Estimated count or percentage]
Current Behavior
<!-- How do these users currently behave? What's the baseline? -->
[Current state]
Success Metrics
Primary Metric
<!-- The main metric that determines if the hypothesis is validated -->
| Metric | Current Baseline | Target | Minimum Detectable Effect |
|---|---|---|---|
| [Metric name] | [Current value] | [Target value] | [MDE %] |
Secondary Metrics
<!-- Additional metrics that provide context -->
| Metric | Current Baseline | Expected Direction |
|---|---|---|
| [Metric 1] | [Value] | [Increase/Decrease/No change] |
| [Metric 2] | [Value] | [Increase/Decrease/No change] |
Guardrail Metrics
<!-- Metrics that should NOT be negatively impacted -->
| Metric | Current Value | Acceptable Range |
|---|---|---|
| [Metric 1] | [Value] | [Range] |
Validation Approach
Method
<!-- How will you test this hypothesis? A/B test, prototype, interviews, etc. -->
[Validation method]
Sample Size & Duration
<!-- Statistical requirements for the test -->
- Sample size: [Number per variant]
- Duration: [Time period]
- Traffic allocation: [Percentage]
Pass/Fail Criteria
<!-- What results will validate or invalidate the hypothesis? -->
- Validated if: [Specific criteria]
- Invalidated if: [Specific criteria]
- Inconclusive if: [Specific criteria]
Risks & Assumptions
Key Assumptions
<!-- What are you assuming to be true? -->
- [Assumption 1]
- [Assumption 2]
Risks
<!-- What could go wrong? What might invalidate results? -->
- [Risk 1]
- [Risk 2]
Timeline
| Phase | Dates | Duration |
|---|---|---|
| Setup & instrumentation | [Dates] | [Duration] |
| Test running | [Dates] | [Duration] |
| Analysis | [Dates] | [Duration] |
| Decision | [Date] | - |
Related skills
How it compares
Use define-hypothesis before PRD or experiment-design skills when the gap is an untested belief, not requirements detail or instrumentation specs.
FAQ
How do you invoke define-hypothesis in Claude Code?
define-hypothesis is invoked with /pm-skills:define-hypothesis plus context, or $define-hypothesis on Codex. The skill outputs a structured belief statement, metrics, validation plan, and risks.
What should come before define-hypothesis in pm-skills?
define-hypothesis typically follows define-problem-statement in pm-skills recipe chains. Problem framing supplies user pain and context; the hypothesis skill adds testable beliefs and measurable outcomes.