Hypotheses

Hypotheses

Helps the user surface, refine, and manage testable assumptions about their idea. These hypotheses are the foundation for interview scripts, surveys, and validation experiments.

Before you start

Read startup/core.md to load project context (name, seed description, and all fields under ## Core).

Check if startup/hypotheses/ contains any .md files.

When hypotheses already exist

Load and understand them for context. Infer intent from the conversation — don't mechanically ask "what do you want to do?" If the user is:

• Talking about a specific assumption — help them refine or update the matching hypothesis
• Questioning new assumptions — help shape new hypotheses following the conventions below
• Reviewing the full set — summarize what exists, grouped by tag type, with status
• Updating status — read the file, propose the status change, get confirmation, write it back
• Archiving — when a hypothesis is no longer relevant (e.g., after a pivot), set status: archived and add archived_reason to frontmatter with a one-line explanation. Archived hypotheses stay in place — they can be restored by flipping the status back
• Wanting web research on a hypothesis — dispatch the web-researcher agent (fast model) with a focused prompt: include the hypothesis statement, the problem space from core.md, and ask for community signals (Reddit, forums), existing workarounds, and willingness-to-pay evidence. Incorporate key findings into the hypothesis ## Notes section. Save the full web-researcher output to startup/research/{YYYY-MM-DD}-{hypothesis-slug}-research.md with frontmatter date, topic, and source_skill: hypotheses

When adding or updating hypotheses, follow the file conventions:

• YAML frontmatter with status (untested, confirmed, invalidated, or archived)
• Optional last_assessed ISO date (YYYY-MM-DD) — set by assessments, not on creation
• H1 heading: the hypothesis as a testable statement
• Obsidian tag on the next line: #problem, #solution, #willingness_to_pay, #urgency, or #other
• Description: what the assumption is, why it matters, what changes if it's wrong
• Optional ## Notes section
• Optional ## Next Action section — the smallest observable next validation move. Advisory and generated by assessments (see below), not authored by hand. No required internal structure: a tight one-sentence directive is the norm. It is overwritten on each assessment, always reflecting the latest reasoning — not an append-only log.

Slug convention: lowercase the title, replace spaces and non-alphanumeric characters with hyphens, collapse multiple hyphens.

Read before writing, propose before saving, get confirmation.

When no hypotheses exist

Check if startup/core.md has at minimum Audience and Problem defined under ## Core.

• If not: Mention that fleshing out the core idea first would help — strongly suggest to do it first, and if the user agrees, invoke the whats-next skill to initialize the project, and then you can come back to hypotheses. But do not block: if the user insists to work on hypotheses now, proceed.
• If yes (or user insists): Load the reference file for the guided first-time conversation:

.claude/skills/hypotheses/references/initial-hypotheses.md

The reference file's instructions take over from this point.

Assessing hypothesis state

State assessment is one of this skill's core capabilities. When hypothesis state is in question, dispatch the hypotheses-manager subagent rather than evaluating evidence inline — it's bias-isolated, reads across interview evidence independently, and returns structured recommendations.

When to dispatch:

• The user asks directly about hypothesis health ("how are my hypotheses looking?", "what do we know so far?", "any hypothesis ready to confirm?", "which of these are we still guessing on?")
• Right after an interview has been analyzed and new [[slug]] backlinks have arrived (this is wired in automatically by the interviews skill's post-transcript flow — you'll see that path in the interviews skill)
• You're orienting the user on what to do next and hypothesis state is material to the decision
• The user questions whether a specific hypothesis still holds, or whether a cross-interview pattern deserves a new hypothesis

What to pass:

• slugs: the keyword all (or a specific list if the conversation is about particular hypotheses)
• scope: include instruction to also synthesize candidate new hypotheses from unlinked statements across interview files