bmad-enhanced 1.6.5 → 1.7.1

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.7.1] - 2026-03-03
+
+### Fixed
+
+- **`bmad-update` failed to upgrade from 1.6.x to 1.7.0** — Missing `1.6.x-to-1.7.0` migration in registry caused "No migrations needed (versions compatible)" instead of running the upgrade. Added migration entry and no-op delta file.
+
+---
+
+## [1.7.0] - 2026-03-02
+
+### Added
+
+- **Docs Audit Tool** (`npm run docs:audit`) — Programmatic documentation quality checker with 5 check types:
+  - Stale numeric references (detects outdated agent/workflow counts)
+  - Broken internal links
+  - Incomplete agent listing tables (with relationship table detection)
+  - Internal naming convention leaks (`_vortex` in user-facing prose)
+  - Forward-compatibility checks
+- **P0 Content Correctness Test Suite** — 12 test files covering activation, voice consistency, content correctness, handoff contracts, and workflow structure for all 7 agents
+- **18 production-quality workflow step files** for Wade's three remaining workflows:
+  - `lean-experiment/steps/` — step-01-hypothesis through step-06-decide
+  - `proof-of-concept/steps/` — step-01-risk through step-06-document
+  - `proof-of-value/steps/` — step-01-value-hypothesis through step-06-document
+- **7 comprehensive user guides** — Created/expanded guides for all 7 agents in `_bmad/bme/_vortex/guides/`
+- **"Your First 15 Minutes" walkthrough** in README — 6-step guided onboarding from config to first artifact
+- **Activation model explanation** in README — explains what agent files are and how Claude adopts personas
+- **Config personalization step** in README Quick Start and installer output
+- **`bmad-update` test suite** — 615+ lines covering upgrade flows, config merging, version detection
+- **`bmad-version` test suite** — 377 lines covering version display, migration history, update detection
+- **`docs-audit` test suite** — 539 lines covering all 5 check functions
+- **7-agent journey example** — Complete busy-parents walkthrough demonstrating all 7 agents and handoff contracts
+- **Structured feedback mechanism** — GitHub issue template for agent/workflow feedback
+
+### Changed
+
+- **CRITICAL: Fixed npm package bloat** — Package reduced from 1618 files / 9.7 MB to 242 files / 1.1 MB. The `files` field in `package.json` was too broad (`"_bmad/"`, `"_bmad-output/"`), shipping internal backups, migration logs, sprint artifacts, and all BMAD modules (bmm, cis, core, tea). Now precisely targets `"_bmad/bme/_vortex/"` only.
+- **Config merger smart-merge** — `mergeConfig()` now preserves user-added agents and workflows during updates. Canonical entries maintain registry order; user-added entries are deduplicated and appended.
+- **User guide invocation methods reordered** — Direct File Reading is now Method 1 (Recommended) in all 7 guides; Slash Command is Method 2 (BMAD Environments Only)
+- **README overhaul** — Value proposition, visual Vortex diagram, agent output previews, Claude Code/Claude.ai activation instructions
+- **Installer output** — Now shows numbered "Next Steps" including config personalization
+- **Journey example condensed** — 944 to 888 lines, tightened transition sections
+- **docs/agents.md** — Updated agent count references, handoff contract documentation
+- **docs/faq.md** — Expanded with workflow and agent questions
+- **INSTALLATION.md** — Updated installation instructions
+- **UPDATE-GUIDE.md** — Added user-agent preservation documentation
+
+### Fixed
+
+- Config merger overwrote user-added agents on upgrade (now preserved via smart-merge)
+- Incomplete agent table detection false positives on relationship/contract-flow tables
+- Internal naming leak check false positives on markdown link targets and backtick-wrapped paths
+- `_vortex` appearing unescaped in 7 user guide Credits sections
+- Separator and header rows incorrectly counted in agent table completeness check
+- README "Type `LP`" instruction meaningless to new users (now "Select **Lean Persona** from the menu")
+- Redundant config personalization step in "Your First 15 Minutes"
+
+### Technical Details
+
+- **Tests:** 309 pass, 0 fail, 0 todo (unit + integration + P0)
+- **Package:** 242 files, 1.1 MB unpacked (was 1618 files, 9.7 MB)
+- **Docs audit:** `npm run docs:audit --json` returns `[]` (zero findings)
+- **All 22 workflows** now have production-quality step content (no placeholders)
+
+---
+
 ## [1.6.0] - 2026-02-26
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@
 
 **Validate your product ideas before writing a single line of code**
 
-[![Version](https://img.shields.io/badge/version-1.6.4-blue)](https://github.com/amalik/BMAD-Enhanced)
+[![Version](https://img.shields.io/badge/version-1.7.0-blue)](https://github.com/amalik/BMAD-Enhanced)
 [![Agents](https://img.shields.io/badge/agents-7-brightgreen)](docs/agents.md)
 [![Workflows](https://img.shields.io/badge/workflows-22-success)](docs/agents.md)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -70,6 +70,10 @@ npm install bmad-enhanced && npx bmad-install-vortex-agents
 
 All 7 agents with 22 workflows are installed and ready to use.
 
+### Personalize
+
+Open `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name. Agents use this to personalize their interactions.
+
 ### Activate an Agent
 
 ```bash
@@ -83,7 +87,23 @@ cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md # Noah  📡
 cat _bmad/bme/_vortex/agents/learning-decision-expert.md          # Max   🧭
 ```
 
-Each agent presents a menu-driven interface. Pick a workflow and follow the guided steps.
+**How activation works:** Each agent is a markdown file containing a full persona, menu system, and workflow instructions. When Claude reads the file, it adopts that agent's expertise and presents you with an interactive menu.
+
+- **Claude Code / Terminal:** Use the `cat` commands above
+- **Claude.ai:** Copy the contents of any agent file and paste into the chat
+
+Pick a workflow from the menu and follow the guided steps.
+
+### Your First 15 Minutes
+
+1. **Personalize** — If you haven't already, edit `_bmad/bme/_vortex/config.yaml` and replace `{user}` with your name
+2. **Activate Emma** — `cat _bmad/bme/_vortex/agents/contextualization-expert.md`
+3. **See the menu** — Emma presents numbered options. Select **Lean Persona** from the menu
+4. **Follow the steps** — Emma walks you through 6 guided steps, asking questions at each one
+5. **Find your artifact** — When done, your lean persona is saved in `_bmad-output/vortex-artifacts/`
+6. **Follow the Compass** — At the end, Emma's Vortex Compass suggests which agent to use next based on what you learned
+
+Each workflow ends with a Compass routing suggestion. You don't need to follow a linear path — the system guides you to whichever stream needs attention.
 
 ### What Gets Installed
 
@@ -225,6 +245,7 @@ BMAD-Enhanced works standalone or as an extension — no BMAD Method installatio
 
 - **v1.1.0–v1.5.x** — Waves 1-2: Foundation (Emma, Isla, Wade, Max — agent definitions, workflows, update system, CI/CD)
 - **v1.6.x** — Wave 3: Complete 7-stream Vortex (added Mila, Liam, Noah — 7 agents, 22 workflows, handoff contracts, Compass routing)
+- **v1.7.0** — Wave 4: Quality & onboarding (P0 test suite, docs audit tool, all 22 workflows production-ready, README overhaul, package size fix)
 - **v2.0.0+** — Multi-agent collaboration, cross-agent workflows, analytics
 
 ---

package/UPDATE-GUIDE.md

@@ -120,7 +120,7 @@ Every update creates a backup before making changes:
 
 - Agent definition files
 - Workflow files (steps, templates, validation)
-- Vortex config.yaml (with preference preservation)
+- Vortex config.yaml (with preference preservation — user-added agents and workflows are kept after core entries)
 - User guides
 
 ---

package/_bmad/bme/_vortex/guides/EMMA-USER-GUIDE.md

@@ -38,35 +38,30 @@ Lean personas focused on jobs-to-be-done and problem contexts, product vision do
 
 ## How to Invoke Emma
 
-### Method 1: Slash Command (Preferred)
+### Method 1: Direct Agent File Reading (Recommended)
 
-If you're in a BMAD environment that supports slash commands:
+Read Emma's agent file to activate her. This works in any environment:
 
+**Claude Code:**
 ```
-/bmad-agent-bme-contextualization-expert
+Read the file at _bmad/bme/_vortex/agents/contextualization-expert.md
 ```
 
-**If you see "Unknown skill":**
-This means slash commands aren't available in your environment. Use Method 2 instead.
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/contextualization-expert.md
+```
 
----
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/contextualization-expert.md` and paste into the chat.
 
-### Method 2: Direct Agent File Reading (Always Works)
+---
 
-In any environment (including Claude Code), you can invoke Emma by reading her agent file:
+### Method 2: Slash Command (BMAD Environments Only)
 
-1. Navigate to your BMAD project root
-2. Read the file: `_bmad/bme/_vortex/agents/contextualization-expert.md`
-3. Emma will activate and greet you
+If your environment supports BMAD slash commands:
 
-**Example (Claude Code):**
 ```
-Read the file at _bmad/bme/_vortex/agents/contextualization-expert.md
-```
-
-**Example (Terminal):**
-```bash
-cat _bmad/bme/_vortex/agents/contextualization-expert.md
+/bmad-agent-bme-contextualization-expert
 ```
 
 ---
@@ -228,7 +223,7 @@ Unclear product strategy wastes everyone's time. Be specific about problem space
 
 **Agent:** Emma (contextualization-expert)
 **Module:** BMAD Enhanced (bme)
-**Submodule:** Vortex Pattern (_vortex)
+**Submodule:** Vortex Pattern (`_vortex`)
 **Stream:** Contextualize (Stream 1)
 **Version:** 1.6.4
 

package/_bmad/bme/_vortex/guides/ISLA-USER-GUIDE.md

@@ -27,35 +27,30 @@ Empathy maps grounded in research, interview guides and findings, discovery rese
 
 ## How to Invoke Isla
 
-### Method 1: Slash Command (Preferred)
+### Method 1: Direct Agent File Reading (Recommended)
 
-If you're in a BMAD environment that supports slash commands:
+Read Isla's agent file to activate her. This works in any environment:
 
+**Claude Code:**
 ```
-/bmad-agent-bme-discovery-empathy-expert
+Read the file at _bmad/bme/_vortex/agents/discovery-empathy-expert.md
 ```
 
-**If you see "Unknown skill":**
-This means slash commands aren't available in your environment. Use Method 2 instead.
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/discovery-empathy-expert.md
+```
 
----
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/discovery-empathy-expert.md` and paste into the chat.
 
-### Method 2: Direct Agent File Reading (Always Works)
+---
 
-In any environment (including Claude Code), you can invoke Isla by reading her agent file:
+### Method 2: Slash Command (BMAD Environments Only)
 
-1. Navigate to your BMAD project root
-2. Read the file: `_bmad/bme/_vortex/agents/discovery-empathy-expert.md`
-3. Isla will activate and greet you
+If your environment supports BMAD slash commands:
 
-**Example (Claude Code):**
 ```
-Read the file at _bmad/bme/_vortex/agents/discovery-empathy-expert.md
-```
-
-**Example (Terminal):**
-```bash
-cat _bmad/bme/_vortex/agents/discovery-empathy-expert.md
+/bmad-agent-bme-discovery-empathy-expert
 ```
 
 ---
@@ -204,7 +199,7 @@ When a participant's voice changes, they lean forward, or they hesitate — that
 
 **Agent:** Isla (discovery-empathy-expert)
 **Module:** BMAD Enhanced (bme)
-**Submodule:** Vortex Pattern (_vortex)
+**Submodule:** Vortex Pattern (`_vortex`)
 **Stream:** Empathize (Stream 2)
 **Version:** 1.5.0
 

package/_bmad/bme/_vortex/guides/LIAM-USER-GUIDE.md

@@ -39,35 +39,30 @@ Hypothesis contracts (HC3 artifacts) containing 1-3 testable hypotheses in 4-fie
 
 ## How to Invoke Liam
 
-### Method 1: Slash Command (Preferred)
+### Method 1: Direct Agent File Reading (Recommended)
 
-If you're in a BMAD environment that supports slash commands:
+Read Liam's agent file to activate him. This works in any environment:
 
+**Claude Code:**
 ```
-/bmad-agent-bme-hypothesis-engineer
+Read the file at _bmad/bme/_vortex/agents/hypothesis-engineer.md
 ```
 
-**If you see "Unknown skill":**
-This means slash commands aren't available in your environment. Use Method 2 instead.
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/hypothesis-engineer.md
+```
 
----
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/hypothesis-engineer.md` and paste into the chat.
 
-### Method 2: Direct Agent File Reading (Always Works)
+---
 
-In any environment (including Claude Code), you can invoke Liam by reading his agent file:
+### Method 2: Slash Command (BMAD Environments Only)
 
-1. Navigate to your BMAD project root
-2. Read the file: `_bmad/bme/_vortex/agents/hypothesis-engineer.md`
-3. Liam will activate and greet you
+If your environment supports BMAD slash commands:
 
-**Example (Claude Code):**
 ```
-Read the file at _bmad/bme/_vortex/agents/hypothesis-engineer.md
-```
-
-**Example (Terminal):**
-```bash
-cat _bmad/bme/_vortex/agents/hypothesis-engineer.md
+/bmad-agent-bme-hypothesis-engineer
 ```
 
 ---
@@ -251,7 +246,7 @@ This is the fundamental test. If there's no result that would make you say "we w
 
 **Agent:** Liam (hypothesis-engineer)
 **Module:** BMAD Enhanced (bme)
-**Submodule:** Vortex Pattern (_vortex)
+**Submodule:** Vortex Pattern (`_vortex`)
 **Stream:** Hypothesize (Stream 4)
 **Version:** 1.6.0
 

package/_bmad/bme/_vortex/guides/MAX-USER-GUIDE.md

@@ -26,35 +26,30 @@ Learning cards, pivot/patch/persevere assessments, Vortex navigation recommendat
 
 ## How to Invoke Max
 
-### Method 1: Slash Command (Preferred)
+### Method 1: Direct Agent File Reading (Recommended)
 
-If you're in a BMAD environment that supports slash commands:
+Read Max's agent file to activate him. This works in any environment:
 
+**Claude Code:**
 ```
-/bmad-agent-bme-learning-decision-expert
+Read the file at _bmad/bme/_vortex/agents/learning-decision-expert.md
 ```
 
-**If you see "Unknown skill":**
-Use Method 2 instead.
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/learning-decision-expert.md
+```
 
----
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/learning-decision-expert.md` and paste into the chat.
 
-### Method 2: Direct Agent File Reading (Always Works)
+---
 
-In any environment (including Claude Code), invoke Max by reading his agent file:
+### Method 2: Slash Command (BMAD Environments Only)
 
-1. Navigate to your BMAD project root
-2. Read the file: `_bmad/bme/_vortex/agents/learning-decision-expert.md`
-3. Max will activate and greet you
+If your environment supports BMAD slash commands:
 
-**Example (Claude Code):**
 ```
-Read the file at _bmad/bme/_vortex/agents/learning-decision-expert.md
-```
-
-**Example (Terminal):**
-```bash
-cat _bmad/bme/_vortex/agents/learning-decision-expert.md
+/bmad-agent-bme-learning-decision-expert
 ```
 
 ---
@@ -209,7 +204,7 @@ A "failed" experiment that clearly invalidates an assumption saves months of bui
 
 **Agent:** Max (learning-decision-expert)
 **Module:** BMAD Enhanced (bme)
-**Submodule:** Vortex Pattern (_vortex)
+**Submodule:** Vortex Pattern (`_vortex`)
 **Stream:** Systematize (Stream 7)
 **Version:** 1.5.0
 

package/_bmad/bme/_vortex/guides/MILA-USER-GUIDE.md

@@ -38,35 +38,30 @@ Evidence-backed problem definitions (HC2 artifacts) grounded in Jobs-to-be-Done
 
 ## How to Invoke Mila
 
-### Method 1: Slash Command (Preferred)
+### Method 1: Direct Agent File Reading (Recommended)
 
-If you're in a BMAD environment that supports slash commands:
+Read Mila's agent file to activate her. This works in any environment:
 
+**Claude Code:**
 ```
-/bmad-agent-bme-research-convergence-specialist
+Read the file at _bmad/bme/_vortex/agents/research-convergence-specialist.md
 ```
 
-**If you see "Unknown skill":**
-This means slash commands aren't available in your environment. Use Method 2 instead.
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/research-convergence-specialist.md
+```
 
----
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/research-convergence-specialist.md` and paste into the chat.
 
-### Method 2: Direct Agent File Reading (Always Works)
+---
 
-In any environment (including Claude Code), you can invoke Mila by reading her agent file:
+### Method 2: Slash Command (BMAD Environments Only)
 
-1. Navigate to your BMAD project root
-2. Read the file: `_bmad/bme/_vortex/agents/research-convergence-specialist.md`
-3. Mila will activate and greet you
+If your environment supports BMAD slash commands:
 
-**Example (Claude Code):**
 ```
-Read the file at _bmad/bme/_vortex/agents/research-convergence-specialist.md
-```
-
-**Example (Terminal):**
-```bash
-cat _bmad/bme/_vortex/agents/research-convergence-specialist.md
+/bmad-agent-bme-research-convergence-specialist
 ```
 
 ---
@@ -231,7 +226,7 @@ A single interview quote is interesting. The same insight appearing across three
 
 **Agent:** Mila (research-convergence-specialist)
 **Module:** BMAD Enhanced (bme)
-**Submodule:** Vortex Pattern (_vortex)
+**Submodule:** Vortex Pattern (`_vortex`)
 **Stream:** Synthesize (Stream 3)
 **Version:** 1.6.0
 

package/_bmad/bme/_vortex/guides/NOAH-USER-GUIDE.md

@@ -40,35 +40,30 @@ HC5 signal reports — contextualized intelligence reports that interpret produc
 
 ## How to Invoke Noah
 
-### Method 1: Slash Command (Preferred)
+### Method 1: Direct Agent File Reading (Recommended)
 
-If you're in a BMAD environment that supports slash commands:
+Read Noah's agent file to activate him. This works in any environment:
 
+**Claude Code:**
 ```
-/bmad-agent-bme-production-intelligence-specialist
+Read the file at _bmad/bme/_vortex/agents/production-intelligence-specialist.md
 ```
 
-**If you see "Unknown skill":**
-This means slash commands aren't available in your environment. Use Method 2 instead.
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md
+```
 
----
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/production-intelligence-specialist.md` and paste into the chat.
 
-### Method 2: Direct Agent File Reading (Always Works)
+---
 
-In any environment (including Claude Code), you can invoke Noah by reading his agent file:
+### Method 2: Slash Command (BMAD Environments Only)
 
-1. Navigate to your BMAD project root
-2. Read the file: `_bmad/bme/_vortex/agents/production-intelligence-specialist.md`
-3. Noah will activate and greet you
+If your environment supports BMAD slash commands:
 
-**Example (Claude Code):**
 ```
-Read the file at _bmad/bme/_vortex/agents/production-intelligence-specialist.md
-```
-
-**Example (Terminal):**
-```bash
-cat _bmad/bme/_vortex/agents/production-intelligence-specialist.md
+/bmad-agent-bme-production-intelligence-specialist
 ```
 
 ---
@@ -254,7 +249,7 @@ Noah produces prioritized, evidence-based signal reports. Noah does not tell you
 
 **Agent:** Noah (production-intelligence-specialist)
 **Module:** BMAD Enhanced (bme)
-**Submodule:** Vortex Pattern (_vortex)
+**Submodule:** Vortex Pattern (`_vortex`)
 **Stream:** Sensitize (Stream 6)
 **Version:** 1.6.0
 

package/_bmad/bme/_vortex/guides/WADE-USER-GUIDE.md

@@ -39,35 +39,30 @@ MVP specifications, lean experiment designs with Build-Measure-Learn structure,
 
 ## How to Invoke Wade
 
-### Method 1: Slash Command (Preferred)
+### Method 1: Direct Agent File Reading (Recommended)
 
-If you're in a BMAD environment that supports slash commands:
+Read Wade's agent file to activate him. This works in any environment:
 
+**Claude Code:**
 ```
-/bmad-agent-bme-lean-experiments-specialist
+Read the file at _bmad/bme/_vortex/agents/lean-experiments-specialist.md
 ```
 
-**If you see "Unknown skill":**
-This means slash commands aren't available in your environment. Use Method 2 instead.
+**Terminal:**
+```bash
+cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md
+```
 
----
+**Claude.ai:** Copy the contents of `_bmad/bme/_vortex/agents/lean-experiments-specialist.md` and paste into the chat.
 
-### Method 2: Direct Agent File Reading (Always Works)
+---
 
-In any environment (including Claude Code), you can invoke Wade by reading his agent file:
+### Method 2: Slash Command (BMAD Environments Only)
 
-1. Navigate to your BMAD project root
-2. Read the file: `_bmad/bme/_vortex/agents/lean-experiments-specialist.md`
-3. Wade will activate and greet you
+If your environment supports BMAD slash commands:
 
-**Example (Claude Code):**
 ```
-Read the file at _bmad/bme/_vortex/agents/lean-experiments-specialist.md
-```
-
-**Example (Terminal):**
-```bash
-cat _bmad/bme/_vortex/agents/lean-experiments-specialist.md
+/bmad-agent-bme-lean-experiments-specialist
 ```
 
 ---
@@ -241,7 +236,7 @@ Failure is only valuable if you learn from it. Document what you learned, why ex
 
 **Agent:** Wade (lean-experiments-specialist)
 **Module:** BMAD Enhanced (bme)
-**Submodule:** Vortex Pattern (_vortex)
+**Submodule:** Vortex Pattern (`_vortex`)
 **Stream:** Externalize (Stream 5)
 **Version:** 1.6.4
 

package/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-01-hypothesis.md

@@ -0,0 +1,58 @@
+---
+step: 1
+workflow: lean-experiment
+title: State Hypothesis & Input Validation
+---
+
+# Step 1: State Hypothesis & Input Validation
+
+Before we run any experiment, we need a clear hypothesis to test. Not a hunch. Not a wish. A falsifiable bet with explicit assumptions you can prove wrong.
+
+## Why This Matters
+
+Experiments without hypotheses produce data without direction. You'll measure things, but you won't know what the results mean. A clear hypothesis tells you exactly what result would change your mind — and that's what makes it an experiment instead of a demo.
+
+## Your Task
+
+### 1. What Hypothesis Are You Testing?
+
+Wade expects a hypothesis — ideally from Liam's hypothesis-engineering workflow as an HC3-compliant artifact:
+- **HC3 Hypothesis Contract** (from Liam's `hypothesis-engineering` workflow)
+- **HC3 with Assumption Risk Map** showing which assumptions to test first
+
+You can also bring **any well-formed hypothesis** — Wade accepts input from outside the Vortex pattern. It doesn't have to be HC3-compliant, but having a structured hypothesis with an explicit riskiest assumption makes experiment design dramatically stronger.
+
+### 2. Provide Your Input
+
+Please provide the file path or describe the hypothesis you want to test. For example:
+- `_bmad-output/vortex-artifacts/hc3-hypothesis-contract-2026-03-01.md`
+- Or: "I believe that [users] will [behavior] because [rationale], and the riskiest assumption is [assumption]"
+
+### 3. Input Validation
+
+I'll check your hypothesis for experiment-readiness:
+
+**Hypothesis Statement Check:**
+- [ ] States what you believe will happen (expected outcome)
+- [ ] Identifies a specific behavior change you expect to observe
+- [ ] Provides rationale grounded in evidence (not intuition)
+- [ ] Names the riskiest assumption — the one thing that could kill this
+
+**Falsifiability Check:**
+- [ ] Can you describe a result that would prove this hypothesis wrong?
+- [ ] Are the expected outcomes specific enough that two people would agree on success vs. failure?
+- [ ] Is the riskiest assumption something you can actually observe or measure?
+
+**If your input is incomplete:** That's okay — we'll work through the gaps. But let's be honest about what we know vs. what we're assuming. The experiment will only be as strong as the hypothesis driving it.
+
+---
+
+## Your Turn
+
+Please provide your hypothesis — file path, description, or both. I'll validate it and we'll proceed to designing the experiment.
+
+## Next Step
+
+When your hypothesis is validated and experiment-ready, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/lean-experiment/steps/step-02-design.md