Propose Hypotheses
Run a full First Principles Framework (FPF) cycle—from competing hypotheses through evidence and trust—to decide what to build or change before committing implementation effort.
Overview
Propose Hypotheses is a journey-wide agent skill that runs the full FPF decision cycle—usable whenever a solo builder needs structured competing hypotheses and an auditable decision before committing.
Install
npx skills add https://github.com/neolabhq/context-engineering-kit --skill propose-hypothesesWhat is this skill?
- End-to-end FPF cycle: hypotheses → logic check → evidence → trust audit → decision
- Scaffolds `.fpf/` with evidence, decisions, sessions, and knowledge tiers L0–L2 plus invalid
- Orchestrates fpf-agent subtasks (init context, generate hypotheses) with defined write targets
- Problem statement driven via `$ARGUMENTS` / argument-hint
- Uses Task, Read, Write, Bash, and AskUserQuestion for collaborative decision runs
- Creates `.fpf/` subtrees for evidence, decisions, sessions, and knowledge tiers L0, L1, L2, and invalid
- Documented multi-step workflow from directory scaffold through fpf-agent hypothesis generation
Adoption & trust: 512 installs on skills.sh; 1.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You face an ambiguous product or technical problem and risk committing to the first idea in chat without competing hypotheses, evidence, or a recorded decision.
Who is it for?
Founders and technical solos who want first-principles rigor, written artifacts, and multi-step agent orchestration before locking scope.
Skip if: Quick one-off code edits where the problem is already specified and approved, or teams unwilling to maintain `.fpf/` files in the repo.
When should I use this skill?
You supply a problem statement and need the complete FPF cycle from hypothesis generation through verification, evidence, trust audit, and decision.
What do I get? / Deliverables
You get a populated `.fpf/` workspace, documented context and L0 hypotheses, and a framework-guided path to a verified decision you can hand to planning or implementation skills next.
- .fpf/context.md context summary
- L0 hypothesis IDs and titles under `.fpf/knowledge/L0/`
- Scaffolded evidence/decisions/sessions directories for the FPF cycle
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Compare three go-to-market hypotheses and record evidence before cutting MVP scope.
Frame competing explanations for user pain before you invest in a landing page test.
Decide between monolith and service split with logged L0/L1 knowledge for the team-of-one future you.
Run hypotheses on intermittent errors and audit trust in monitoring data before a refactor.
Choose launch sequencing options with explicit invalidation paths for rejected strategies.
How it compares
Structured FPF workflow with on-disk knowledge tiers—not informal brainstorming or a single-shot LLM opinion.
Common Questions / FAQ
Who is propose-hypotheses for?
Solo and indie builders using Claude Code-style agents who need disciplined hypothesis generation and decisions for product, architecture, or strategy questions.
When should I use propose-hypotheses?
Use it in Validate when scoping what to build; in Idea when framing research questions; in Build when choosing between architectural forks; and in Operate when diagnosing recurring production issues with competing root causes.
Is propose-hypotheses safe to install?
It instructs agents to write directories and run Bash; review the Security Audits panel on this page and restrict repo access if you do not want automated file creation under `.fpf/`.
SKILL.md
READMESKILL.md - Propose Hypotheses
# Propose Hypotheses Workflow Execute the First Principles Framework (FPF) cycle: generate competing hypotheses, verify logic, validate evidence, audit trust, and produce a decision. ## User Input ```text Problem Statement: $ARGUMENTS ``` ## Workflow Execution ### Step 1a: Create Directory Structure (Main Agent) Create `.fpf/` directory structure if it does not exist: ```bash mkdir -p .fpf/{evidence,decisions,sessions,knowledge/{L0,L1,L2,invalid}} touch .fpf/{evidence,decisions,sessions,knowledge/{L0,L1,L2,invalid}}/.gitkeep ``` **Postcondition**: `.fpf/` directory scaffold exists. --- ### Step 1b: Initialize Context (FPF Agent) Launch fpf-agent with sonnet[1m] model: - **Description**: "Initialize FPF context" - **Prompt**: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/init-context.md and execute. Problem Statement: $ARGUMENTS **Write**: Context summary to `.fpf/context.md`** ``` --- ### Step 2: Generate Hypotheses (FPF Agent) Launch fpf-agent with sonnet[1m] model: - **Description**: "Generate L0 hypotheses" - **Prompt**: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/generate-hypotheses.md and execute. Problem Statement: $ARGUMENTS Context: <summary from Step 1b> **Write**: List of hypothesis IDs and titles to `.fpf/knowledge/L0/` Reply with summary table in markdown format: | ID | Title | Kind | Scope | |----|-------|------|-------| | ... | ... | ... | ... | ``` --- ### Step 3: Present Summary (Main Agent) 1. Read all L0 hypothesis files from `.fpf/knowledge/L0/` 2. Present summary table from agent response. 3. Ask user: "Would you like to add any hypotheses of your own? (yes/no)" --- ### Step 4: Add User Hypothesis (FPF Agent, Conditional Loop) **Condition**: User says yes to adding hypotheses. Launch fpf-agent with sonnet[1m] model: - **Description**: "Add user hypothesis" - **Prompt**: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/add-user-hypothesis.md and execute. User Hypothesis Description: <get from user> **Write**: User hypothesis to `.fpf/knowledge/L0/` ``` **Loop**: Return to Step 3 after hypothesis is added. **Exit**: When user says no or declines to add more. --- ### Step 5: Verify Logic (Parallel Sub-Agents) **Condition**: User finished adding hypotheses. For EACH L0 hypothesis file in `.fpf/knowledge/L0/`, launch parallel fpf-agent with sonnet[1m] model: - **Description**: "Verify hypothesis: <hypothesis-id>" - **Prompt**: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/verify-logic.md and execute. Hypothesis ID: <hypothesis-id> Hypothesis File: .fpf/knowledge/L0/<hypothesis-id>.md **Move**: After you complete verification, move the file to `.fpf/knowledge/L1/` or `.fpf/knowledge/invalid/`. ``` **Wait for all agents**, then check that files are moved to `.fpf/knowledge/L1/` or `.fpf/knowledge/invalid/`. --- ### Step 6: Validate Evidence (Parallel Sub-Agents) For EACH L1 hypothesis file in `.fpf/knowledge/L1/`, launch parallel fpf-agent with sonnet[1m] model: - **Description**: "Validate hypothesis: <hypothesis-id>" - **Prompt**: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/validate-evidence.md and execute. Hypothesis ID: <hypothesis-id> Hypothesis File: .fpf/knowledge/L1/<hypothesis-id>.md **Move**: After you complete validation, move the file to `.fpf/knowledge/L2/` or `.fpf/knowledge/invalid/`. ``` **Wait for all agents**, then check that files are moved to `.fpf/knowledge/L2/` or `.fpf/knowledge/invalid/`. --- ### Step 7: Audit Trust (Parallel Sub-Agents) For EACH L2 hypothesis file in `.fpf/knowledge/L2/`, launch parallel fpf-agent with sonnet[1m] model: - **Description**: "Audit trust: <hypothesis-id>" - **Prompt**: ``` Read ${CLAUDE_PLUGIN_ROOT}/tasks/audit-trust.md and execute. Hypothesis ID: <hypothesis-id> Hypothesis Fi