davepoon/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

What comes back: a structured block of state recommendations — each with a What changed line, reasoning, evidence pointers, and a Next action — plus a single cross-hypothesis Top pick and any candidate new hypotheses. The subagent never edits files.

What to do with the result:

• First (no user confirmation needed) — eager bookkeeping: for every hypothesis the subagent actually evaluated, update two things in its file:
  • Its last_assessed frontmatter to today's date.
  • Its ## Next Action section to the subagent's suggested next action (create the section if absent, overwrite it if present). Both are mechanical, advisory bookkeeping — a factual record of what the subagent recommended against current evidence. Neither changes status or the hypothesis body, so neither needs per-item approval. Writing the next action eagerly keeps hypothesis files a live dashboard (the whats-next skill reads these sections) and keeps the stability anchor accurate even if the user nods and closes the chat, or if the assessment ran as a byproduct of another flow. (Read the file before writing, so you only touch frontmatter and the ## Next Action section.)
• Then surface the state recommendations conversationally — lead each touched hypothesis with what changed → the next action, not just a status. Surface the Top pick as the single most pressing move. Then any candidate new hypotheses.
• For each recommended status change, use this skill's normal propose-before-writing flow — confirm per-item before flipping status.
• For each candidate new hypothesis, get the user's go-ahead before creating a file following the conventions above.
• Do not flip statuses or create new hypothesis files without explicit per-item confirmation.

This is the same subagent dispatched by the interviews skill after a transcript is analyzed — so state assessment is centralized here regardless of which entry point triggers it.

---

Ad-hoc web search vs. dispatching web-researcher

Not every web question needs a subagent:

• Inline WebSearch / WebFetch (you, the main agent): single-fact lookups ("is this Reddit thread still active?", "what's the latest on X pricing model?"), quick verification of a claim, one data point asked about in flow. Stays in conversation, no persistence needed.
• Dispatch web-researcher: multi-source validation passes for a specific hypothesis (scanning community signals across Reddit/HN/forums, surveying workarounds, gathering willingness-to-pay evidence). Output is structured and gets saved to startup/research/{YYYY-MM-DD}-{hypothesis-slug}-research.md for later reference — and the findings feed into the hypothesis's ## Notes section.

Rough rule: one fact in flow → inline. Multi-source or results-should-persist → dispatch.