convoke-agents 2.0.0

package/_bmad/bme/_vortex/contracts/hc3-hypothesis-contract.md

@@ -0,0 +1,112 @@
+# HC3: Hypothesis Contract — Schema Definition
+
+> **Contract:** HC3 | **Type:** Artifact | **Flow:** Liam → Wade
+>
+> This schema defines the structure for hypothesis contracts produced during hypothesis engineering. Each artifact contains 1-3 investment-grade hypotheses with explicit riskiest assumptions, ready for experiment design. Any agent or user can produce a compliant artifact — the schema is not coupled to a specific producer.
+
+## Frontmatter Schema
+
+```yaml
+---
+contract: HC3
+type: artifact
+source_agent: liam                          # or any producing agent/user
+source_workflow: hypothesis-engineering      # workflow that produced this artifact
+target_agents: [wade]                        # primary consumer(s)
+input_artifacts:                             # references to upstream HC2 artifact consumed
+  - path: "_bmad-output/vortex-artifacts/hc2-example.md"
+    contract: HC2
+created: YYYY-MM-DD
+---
+```
+
+### Frontmatter Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `contract` | Yes | string | Always `HC3` |
+| `type` | Yes | string | Always `artifact` |
+| `source_agent` | Yes | string | Agent ID that produced this artifact (e.g., `liam`) |
+| `source_workflow` | Yes | string | Workflow name (e.g., `hypothesis-engineering`, `experiment-design`) |
+| `target_agents` | Yes | array | Agent IDs that consume this artifact (e.g., `[wade]`) |
+| `input_artifacts` | Yes | array | References to HC2 problem definitions or other source material used |
+| `created` | Yes | date | ISO date when artifact was created |
+
+---
+
+## Body Structure
+
+### 1. Problem Context *(required)*
+
+Brief summary of the problem definition this hypothesis set addresses.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Problem Statement | Yes | The converged problem statement from HC2 (or equivalent source) |
+| JTBD Reference | Yes | The primary Job-to-be-Done being addressed |
+| Key Pains Targeted | Yes | Which pains from the problem definition these hypotheses address |
+
+### 2. Hypothesis Contracts *(required, 1-3 per artifact)*
+
+Each hypothesis follows the 4-field format. Repeat this section for each hypothesis (minimum 1, maximum 3).
+
+#### Hypothesis {N}: {Title}
+
+**The 4-Field Contract:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Expected Outcome | Yes | What we expect to happen if the hypothesis is correct. Specific, measurable result. |
+| Target Behavior Change | Yes | What specific user behavior will change, and in what direction. Observable and measurable. |
+| Rationale | Yes | Why we believe this will work — grounded in evidence from HC2 problem definition. |
+| Riskiest Assumption | Yes | The single assumption that, if wrong, invalidates the entire hypothesis. This is what must be tested first. |
+
+**Hypothesis Statement** *(required)*:
+
+> We believe that [target users] will [expected behavior] because [rationale].
+
+### 3. Assumption Risk Map *(required)*
+
+All assumptions across all hypotheses, classified by risk.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Assumption | Yes | Statement of what is assumed |
+| Hypothesis | Yes | Which hypothesis (1, 2, or 3) this assumption belongs to |
+| Lethality | Yes | `High` (if wrong, kills the idea) / `Medium` (if wrong, requires pivot) / `Low` (if wrong, minor adjustment) |
+| Uncertainty | Yes | `High` (no evidence) / `Medium` (some evidence) / `Low` (strong evidence) |
+| Priority | Yes | Derived from lethality × uncertainty — `Test First` / `Test Soon` / `Monitor` |
+| Validation Status | Yes | `Unvalidated` / `Partially Validated` / `Validated` |
+
+### 4. Recommended Testing Order *(required)*
+
+Prioritized sequence for validating assumptions through experiments.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Priority | Yes | Sequence number (1 = test first) |
+| Assumption | Yes | Which assumption to test |
+| Suggested Method | Yes | Recommended experiment approach |
+| Minimum Evidence | Yes | What evidence would validate or invalidate this assumption |
+
+### 5. Flagged Concerns *(optional)*
+
+Assumptions or issues identified during hypothesis engineering that may require routing back to Isla for additional discovery.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Concern | Yes | Description of the unvalidated assumption or knowledge gap |
+| Impact | Yes | How this affects the hypothesis quality |
+| Recommended Action | Yes | Suggested next step (e.g., "Route to Isla for targeted user research") |
+
+---
+
+## Downstream Consumption
+
+**Wade** (primary consumer) uses this artifact to:
+- Design experiments targeting the riskiest assumptions first
+- Use the hypothesis statement format directly as experiment hypothesis
+- Reference expected outcomes when defining success criteria
+- Use the 4-field contract as the experiment brief
+
+**Other consumers:** Isla (for assumption validation routing), Max (for evidence tracking via learning cards).

package/_bmad/bme/_vortex/contracts/hc4-experiment-context.md

@@ -0,0 +1,140 @@
+# HC4: Experiment Context — Schema Definition
+
+> **Contract:** HC4 | **Type:** Artifact | **Flow:** Wade → Noah
+>
+> This schema defines the structure for graduated experiment context produced after an experiment completes and is ready for production signal interpretation. Any agent or user can produce a compliant artifact — the schema is not coupled to a specific producer.
+
+## Frontmatter Schema
+
+```yaml
+---
+contract: HC4
+type: artifact
+source_agent: wade                          # or any producing agent/user
+source_workflow: lean-experiment             # workflow that produced this artifact
+target_agents: [noah]                        # primary consumer(s)
+input_artifacts:                             # references to upstream HC3 artifact consumed
+  - path: "_bmad-output/vortex-artifacts/hc3-example.md"
+    contract: HC3
+created: YYYY-MM-DD
+---
+```
+
+### Frontmatter Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `contract` | Yes | string | Always `HC4` |
+| `type` | Yes | string | Always `artifact` |
+| `source_agent` | Yes | string | Agent ID that produced this artifact (e.g., `wade`) |
+| `source_workflow` | Yes | string | Workflow name (e.g., `lean-experiment`, `proof-of-concept`, `proof-of-value`, `mvp`) |
+| `target_agents` | Yes | array | Agent IDs that consume this artifact (e.g., `[noah]`) |
+| `input_artifacts` | Yes | array | References to HC3 hypothesis contracts or other source material used |
+| `created` | Yes | date | ISO date when artifact was created |
+
+---
+
+## Body Structure
+
+### 1. Experiment Summary *(required)*
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Experiment Name | Yes | Descriptive name for the experiment |
+| One-Sentence Description | Yes | What was tested and why, in one sentence |
+| Experiment Type | Yes | `Lean Experiment` / `Proof of Concept` / `Proof of Value` / `MVP` |
+| Actual Duration | Yes | How long the experiment actually ran (e.g., "3 weeks") |
+| Graduation Status | Yes | `Graduated` (moving to production) / `Completed` (results captured, not graduating) / `Terminated` (stopped early) |
+
+### 2. Hypothesis Tested *(required)*
+
+The hypothesis from HC3 that was tested, in the standard format.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Hypothesis Statement | Yes | `"We believe that [target users] will [expected behavior] because [rationale]"` |
+| Riskiest Assumption | Yes | The assumption this experiment targeted |
+| Original Expected Outcome | Yes | What was expected to happen |
+| Original Target Behavior Change | Yes | What behavior change was expected |
+
+### 3. Experiment Method *(required)*
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Method Type | Yes | Description of experiment methodology |
+| Sample Size | Yes | Number of participants or data points |
+| Planned Duration | Yes | Originally planned time period for the experiment |
+| Recruitment/Selection | No | How participants were selected |
+| Controls | No | Control group or baseline comparison |
+
+### 4. Pre-Defined Success Criteria *(required)*
+
+Success criteria as defined **before** seeing results. This is critical for honest evaluation.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Metric | Yes | What was measured |
+| Target Threshold | Yes | The pre-defined success threshold |
+| Actual Result | Yes | What was actually observed |
+| Met? | Yes | `Yes` / `No` / `Partially` |
+
+### 5. Additional Results *(optional)*
+
+Results beyond the pre-defined success criteria in Section 4. Section 4 covers the primary metrics with pass/fail assessment. This section captures supplementary data.
+
+#### Additional Quantitative Metrics
+
+Metrics tracked during the experiment that were not part of the pre-defined success criteria.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Metric | Yes | What was measured (must NOT duplicate Section 4 metrics) |
+| Value | Yes | Observed value |
+| Relevance | Yes | Why this metric matters beyond the primary success criteria |
+
+#### Qualitative Results
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Key Quotes | No | Notable user quotes observed during experiment |
+| Observed Behaviors | No | Significant behaviors not captured by metrics |
+| Unexpected Findings | No | Anything surprising that wasn't part of the hypothesis |
+
+### 6. Confirmed/Rejected Hypotheses *(required)*
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Hypothesis Status | Yes | `Confirmed` / `Rejected` / `Partially Confirmed` / `Inconclusive` |
+| Assumption Status | Yes | Per-assumption: `Validated` / `Invalidated` / `Partially Validated` / `Unresolved` |
+| Core Learning | Yes | One-sentence summary: `"We [validated/invalidated] that [core hypothesis], discovering that [key insight]"` |
+| Conditions | No | Under what conditions the hypothesis holds or fails |
+
+### 7. Strategic Context *(required)*
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Vortex Stream | Yes | Which stream this experiment belongs to |
+| Assumption Tested | Yes | Which assumption from the Vortex journey was tested |
+| Decision It Informs | Yes | What decision this experiment result enables |
+| Implications | Yes | What this means for the product direction |
+
+### 8. Production Readiness *(required for graduated experiments)*
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Metrics to Monitor | Yes | Which production metrics should be tracked |
+| Expected Production Behavior | Yes | What behavior is expected at scale |
+| Signal Thresholds | Yes | When a production signal should trigger attention |
+| Monitoring Duration | No | Recommended production monitoring period |
+
+---
+
+## Downstream Consumption
+
+**Noah** (primary consumer) uses this artifact to:
+- Connect production signals to their originating experiment context
+- Interpret whether production behavior aligns with experiment expectations
+- Detect unexpected behavior patterns not covered by the original hypothesis
+- Produce HC5 signal reports grounded in experiment lineage
+
+**Other consumers:** Max (via learning-card workflow for experiment-to-learning tracking).

package/_bmad/bme/_vortex/contracts/hc5-signal-report.md

@@ -0,0 +1,130 @@
+# HC5: Signal Report — Schema Definition
+
+> **Contract:** HC5 | **Type:** Artifact | **Flow:** Noah → Max
+>
+> This schema defines the structure for production signal reports that interpret production data through experiment lineage. The report produces **intelligence, not strategy** — no strategic recommendations are included. Any agent or user can produce a compliant artifact — the schema is not coupled to a specific producer.
+
+## Frontmatter Schema
+
+```yaml
+---
+contract: HC5
+type: artifact
+source_agent: noah                          # or any producing agent/user
+source_workflow: signal-interpretation       # workflow that produced this artifact
+target_agents: [max]                         # primary consumer(s)
+input_artifacts:                             # references to upstream HC4 artifact consumed
+  - path: "_bmad-output/vortex-artifacts/hc4-example.md"
+    contract: HC4
+created: YYYY-MM-DD
+---
+```
+
+### Frontmatter Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `contract` | Yes | string | Always `HC5` |
+| `type` | Yes | string | Always `artifact` |
+| `source_agent` | Yes | string | Agent ID that produced this artifact (e.g., `noah`) |
+| `source_workflow` | Yes | string | Workflow name (e.g., `signal-interpretation`, `behavior-analysis`, `production-monitoring`) |
+| `target_agents` | Yes | array | Agent IDs that consume this artifact (e.g., `[max]`) |
+| `input_artifacts` | Yes | array | References to HC4 experiment context or other source material used |
+| `created` | Yes | date | ISO date when artifact was created |
+
+---
+
+## Body Structure
+
+### 1. Signal Description *(required)*
+
+Clear, factual description of the production signal observed. No interpretation yet — just what happened.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Signal Summary | Yes | One-sentence factual description of what was observed in production |
+| Signal Type | Yes | `Metric Deviation` / `Behavior Pattern` / `Anomaly` / `Trend Shift` / `Threshold Breach` |
+| Severity | Yes | `Critical` / `Warning` / `Informational` |
+| Detection Method | Yes | How the signal was detected (monitoring, user report, metric analysis, etc.) |
+| Time Window | Yes | When the signal was observed (date range) |
+| Affected Scope | Yes | Which users, segments, or features are affected |
+
+### 2. Context *(required)*
+
+Connection between the production signal and its experiment lineage through the Vortex.
+
+#### Experiment Lineage
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Originating Experiment | Yes | Name and reference to the HC4 experiment that led to this production state |
+| Original Hypothesis | Yes | The hypothesis that was tested |
+| Experiment Outcome | Yes | Whether the hypothesis was confirmed, rejected, or partially confirmed |
+| Expected Production Behavior | Yes | What was expected to happen in production based on experiment results |
+| Actual vs Expected | Yes | How the observed signal compares to experiment expectations |
+
+#### Vortex History
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Problem Definition | No | Reference to the HC2 problem definition in the Vortex journey |
+| Hypothesis Origin | No | Reference to the HC3 hypothesis contract |
+| Previous Signals | No | References to prior HC5 signal reports for this experiment/feature |
+| Related Experiments | No | Other experiments that may be influencing the same production area |
+
+### 3. Trend Analysis *(required)*
+
+Data-driven analysis of the signal's trajectory.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Trend Direction | Yes | `Improving` / `Degrading` / `Stable` / `Oscillating` / `Insufficient Data` |
+| Trend Duration | Yes | How long the trend has been observed |
+| Rate of Change | Yes | How quickly the signal is moving (e.g., "5% week-over-week decline") |
+| Baseline Comparison | Yes | Comparison to pre-experiment or validated baseline |
+| Confidence | Yes | `High` / `Medium` / `Low` — based on data quality and sample size |
+
+### 4. Anomaly Detection *(optional, required when unexpected patterns detected)*
+
+Unexpected user behavior patterns not covered by the original experiment hypothesis (FR15).
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Anomaly Description | Yes | What unexpected behavior was observed |
+| Deviation from Expected | Yes | How this differs from what the experiment predicted |
+| Potential Explanations | Yes | Possible reasons for the anomaly (factual, not speculative strategy) |
+| Discovery Needed | Yes | Whether this warrants routing to Isla for investigation (`Yes` / `No`) |
+| Discovery Focus | No | If yes, what specific questions should Isla investigate |
+
+### 5. Data Quality *(required)*
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Sample Size | Yes | Volume of data underlying this signal |
+| Data Completeness | Yes | Whether data collection was complete or had gaps |
+| Known Biases | No | Any sampling or measurement biases that may affect interpretation |
+| Confidence Level | Yes | `High` / `Medium` / `Low` |
+
+---
+
+## Constraints
+
+**This artifact explicitly does NOT include:**
+- Strategic recommendations (that is Max's domain)
+- Pivot/patch/persevere decisions (that is Max's domain)
+- Experiment design suggestions (that is Liam/Wade's domain)
+- Resource allocation recommendations (that is Max's domain)
+
+Noah produces **intelligence** — contextual, evidence-based signal interpretation. Max produces **decisions**.
+
+---
+
+## Downstream Consumption
+
+**Max** (primary consumer) uses this artifact to:
+- Feed into `learning-card` workflow: the signal report provides experiment context (name, hypothesis, method, success criteria, strategic context) that step-01 requires
+- Feed into `pivot-patch-persevere` workflow: signals organized as STAY/CHANGE/UNCLEAR evidence
+- Feed into `vortex-navigation` workflow: signal contributes to 7-stream status assessment
+- Make evidence-based decisions grounded in production reality
+
+**Other consumers:** Isla (when anomaly detection triggers discovery routing via HC10 Compass guidance).

package/_bmad/bme/_vortex/examples/hc2-example-problem-definition.md

@@ -0,0 +1,85 @@
+---
+contract: HC2
+type: artifact
+source_agent: mila
+source_workflow: research-convergence
+target_agents: [liam]
+input_artifacts:
+  - path: "_bmad-output/vortex-artifacts/hc1-empathy-map-busy-parents-2026-02-20.md"
+    contract: HC1
+  - path: "_bmad-output/vortex-artifacts/hc1-interview-synthesis-working-parents-2026-02-21.md"
+    contract: HC1
+  - path: "_bmad-output/vortex-artifacts/hc1-discovery-report-meal-planning-2026-02-22.md"
+    contract: HC1
+created: 2026-02-23
+---
+
+# HC2 Problem Definition: Busy Parents Meal Planning
+
+> **This is an example artifact** demonstrating the HC2 schema format. It shows what a real output from Mila's research-convergence workflow looks like.
+
+## 1. Converged Problem Statement
+
+**Problem Statement:** Busy dual-income parents spend more time deciding what to feed their families than actually preparing meals, leading to daily decision fatigue that cascades into guilt, nutritional compromise, and reliance on expensive convenience options. Existing meal planning tools assume users have 30-60 minutes to plan weekly — a luxury these parents don't have — creating a gap between available solutions and the reality of time-constrained family feeding.
+
+**Confidence:** High
+
+Multiple artifacts converge on the same core problem with strong, consistent evidence from 28 participants across 3 research methods. All 3 artifacts independently surface time-as-constraint and decision-fatigue as primary themes.
+
+**Scope:**
+- **In scope:** Weeknight dinner planning and preparation for families with children ages 2-12, dual-income households, urban/suburban settings
+- **Out of scope:** Meal prep for special dietary needs (medical), restaurant/takeout optimization, grocery delivery logistics, weekend/holiday meal planning
+
+## 2. Jobs-to-be-Done
+
+### Primary JTBD
+
+> **When** I'm standing in the kitchen at 5:30 PM after a full workday with hungry children asking "what's for dinner?",
+> **I want to** know exactly what to make with what I already have — without thinking,
+> **so I can** feed my family something decent in under 30 minutes and reclaim that mental energy for bedtime routines and connection.
+
+### Job Types
+
+**Functional Job:** Produce a nutritionally acceptable weeknight dinner using available ingredients within 30 minutes of arriving home, with minimal decision-making required.
+- Evidence: 22 of 28 participants described the "5:30 PM panic" moment. 6 of 8 interview subjects mentioned the specific time constraint of 30 minutes. Observation data showed average decision-to-plate time of 47 minutes, of which 18 minutes was decision-making.
+
+**Emotional Job:** Feel like a competent parent who feeds their family well, without the guilt of choosing convenience over nutrition.
+- Evidence: Empathy map "Feels" quadrant showed guilt as the #1 emotion (mentioned by 9 of 12 empathy map participants). Interview quote: "I know I should be doing better. My mom made everything from scratch and I can barely manage a box of mac and cheese some nights."
+
+**Social Job:** Not be judged by partner, in-laws, or other parents for feeding children "poorly" — maintain the appearance of having family meals under control.
+- Evidence: 4 of 8 interview subjects mentioned partner judgment or comparison to other families. Observation report noted 3 instances of participants minimizing their convenience food use when describing meals to others.
+
+## 3. Pains
+
+| Pain Description | Priority | Frequency | Intensity | Evidence Sources | Current Coping |
+|-----------------|----------|-----------|-----------|-----------------|----------------|
+| Decision fatigue at 5:30 PM — too many options, too little energy to choose | High | Daily (weeknights) | Blocks all other evening activities for 15-20 minutes | Empathy map (9/12 participants), Interviews (6/8 subjects), Observations (all 8 sessions) | Default to 3-4 "rotation meals" that require no thought |
+| Existing tools require upfront planning time parents don't have | High | Weekly (when attempting to plan) | 2 of 8 interview subjects abandoned meal planning apps within a week | Interviews (6/8 mentioned tool abandonment), Discovery report (4 app reviews analyzed) | Stop using tools, revert to mental lists or nothing |
+| Guilt about nutritional quality of convenience choices | Medium | 3-4 times/week | Emotional toll described as "constant low-grade guilt" | Empathy map (9/12 "guilt" in Feels), Interviews (5/8 unprompted guilt mentions) | Compensate with weekend "healthy meals" that take 2+ hours |
+| Partner coordination on meals creates hidden overhead | Medium | Daily | 15-20 minutes of texting/calling about dinner plans | Interviews (4/8 mentioned coordination), Observations (3/8 observed texting about meals) | One partner defaults to "just handle it" role |
+
+## 4. Gains
+
+| Gain Description | Priority | Expected Impact | Evidence Sources |
+|-----------------|----------|----------------|-----------------|
+| Know what's for dinner before 5:30 PM without spending time planning | High | Eliminates daily decision fatigue, saves 15-20 min/day of mental load | Interviews (6/8 described ideal as "someone just tells me what to make"), Empathy map ("I just want someone to tell me it's okay to not do everything") |
+| Feel confident that meals are "good enough" nutritionally | High | Reduces guilt, improves emotional well-being around family feeding | Empathy map (Feels/Thinks quadrants), Interviews (5/8 want "nutritional reassurance") |
+| Meals that use what's already in the kitchen — no special shopping trips | Medium | Saves 2-3 unplanned grocery stops per week (avg. 20 min each) | Observations (5/8 sessions showed unplanned grocery stops), Interviews (3/8 mentioned "ingredient gap" as meal plan breaker) |
+
+## 5. Evidence Summary
+
+| Field | Details |
+|-------|---------|
+| **Artifacts Analyzed** | 3 HC1 artifacts: Empathy Map (12 participants), Interview Synthesis (8 semi-structured interviews, 45 min each), Discovery Report (8 observation sessions, 2 hours each) |
+| **Total Evidence Points** | 47 discrete evidence points across all 3 artifacts (22 direct quotes, 14 behavioral observations, 11 survey/count data points) |
+| **Convergence Assessment** | High — all 3 artifacts independently converge on the same core problem (time-as-constraint + decision-fatigue). No artifact contradicts the primary finding. Theme strength: Universal (3/3 artifacts). |
+| **Contradictions** | Minor: Empathy map suggests users want "more meal options" while interviews reveal they feel "overwhelmed by choice." Resolved: users want more *appropriate* options (filtered for their constraints), not more options in general. The desire is for curation, not volume. |
+| **Evidence Gaps** | (1) No data on willingness to pay for a solution — all research focused on problem, not solution. (2) Limited data on single-parent households (only 2 of 28 participants). (3) No longitudinal data on whether decision fatigue worsens seasonally. |
+
+## 6. Assumptions
+
+| Assumption | Basis | Risk if Wrong | Validation Status |
+|-----------|-------|---------------|-------------------|
+| The 5:30 PM decision point is the critical intervention moment | 22 of 28 participants described this timing; observation data confirms peak stress at this time | If the real bottleneck is earlier (e.g., grocery shopping), solving at 5:30 PM won't help | Partially Validated — strong evidence for the timing, but no data on whether earlier intervention would be more effective |
+| "Good enough" nutritional quality is an acceptable bar for these users | 5 of 8 interview subjects used this phrase or equivalent; guilt evidence suggests aspiration exceeds current behavior | If users actually want gourmet/perfect nutrition, a "good enough" solution will feel like failure | Partially Validated — consistent language across interviews, but sample may not represent health-conscious segment |
+| Partner coordination overhead is a real pain, not just a complaint | 4 of 8 interviews + 3 observations showed coordination behavior | If coordination is actually working fine and users are just venting, solving this adds no value | Assumed — behavioral evidence is moderate but not universal (4 of 8) |

package/_bmad/bme/_vortex/examples/hc3-example-hypothesis-contract.md

@@ -0,0 +1,103 @@
+---
+contract: HC3
+type: artifact
+source_agent: liam
+source_workflow: hypothesis-engineering
+target_agents: [wade]
+input_artifacts:
+  - path: "_bmad-output/vortex-artifacts/hc2-problem-definition-busy-parents-2026-02-23.md"
+    contract: HC2
+created: 2026-02-24
+---
+
+# HC3 Hypothesis Contract: Busy Parents Meal Planning
+
+> **This is an example artifact** demonstrating the HC3 schema format. It shows what a real output from Liam's hypothesis-engineering workflow looks like — 3 hypothesis contracts in 4-field format with an assumption risk map and recommended testing order.
+
+## 1. Problem Context
+
+| Field | Details |
+|-------|---------|
+| **Problem Statement** | Busy dual-income parents spend more time deciding what to feed their families than actually preparing meals, leading to daily decision fatigue that cascades into guilt, nutritional compromise, and reliance on expensive convenience options. Existing meal planning tools assume users have 30-60 minutes to plan weekly — a luxury these parents don't have. |
+| **JTBD Reference** | When I'm standing in the kitchen at 5:30 PM after a full workday with hungry children, I want to know exactly what to make with what I already have — without thinking — so I can feed my family something decent in under 30 minutes and reclaim that mental energy for bedtime routines and connection. |
+| **Key Pains Targeted** | (1) Decision fatigue at 5:30 PM — too many options, too little energy to choose. (2) Existing tools require upfront planning time parents don't have. (3) Guilt about nutritional quality of convenience choices. |
+
+## 2. Hypothesis Contracts
+
+### Hypothesis 1: The 5:30 PM Decision Eliminator
+
+**The 4-Field Contract:**
+
+| Field | Details |
+|-------|---------|
+| **Expected Outcome** | Parents using a context-aware meal suggestion system will reduce weeknight dinner decision time from an average of 18 minutes to under 3 minutes, while maintaining or improving their self-reported nutritional satisfaction. |
+| **Target Behavior Change** | Parents will stop the "stand in the kitchen and scroll recipes" behavior and instead act on a single push notification suggesting tonight's dinner based on what's in their kitchen, dietary patterns, and time available. The target behavior is immediate action on a suggestion rather than deliberation. |
+| **Rationale** | The HC2 evidence shows decision fatigue is the core pain (22/28 participants describe the "5:30 PM panic"), and 6/8 interview subjects said their ideal is "someone just tells me what to make." The problem isn't lack of recipes — it's lack of a decision. A system that eliminates the decision entirely addresses the functional JTBD directly. |
+| **Riskiest Assumption** | Parents will trust an automated suggestion enough to act on it without second-guessing. The decision fatigue evidence proves they want someone to decide — but "someone" may need to be a trusted person, not an algorithm. If users don't trust the suggestion, they'll still deliberate, and the 18-minute decision time won't decrease. |
+
+**Hypothesis Statement:**
+> We believe that busy dual-income parents will act on a context-aware dinner suggestion within 3 minutes of receiving it because they are desperate to eliminate the daily decision burden and will trade control for speed when the suggestion accounts for what's already in their kitchen.
+
+---
+
+### Hypothesis 2: The Guilt-Free Nutrition Signal
+
+**The 4-Field Contract:**
+
+| Field | Details |
+|-------|---------|
+| **Expected Outcome** | Parents who receive a simple "nutrition score" (green/yellow/red) with each meal suggestion will report a 40% reduction in meal-related guilt, measured by weekly self-assessment, compared to parents who receive suggestions without nutrition scoring. |
+| **Target Behavior Change** | Parents will shift from compensatory behavior (weekend "healthy meals" that take 2+ hours to make up for weeknight shortcuts) to consistent "good enough" weeknight meals. The target is reducing weekend overcompensation by 50% as parents gain confidence in weeknight nutrition quality. |
+| **Rationale** | The HC2 evidence shows guilt is the #1 emotion (9/12 empathy map participants), and 5/8 interview subjects want "nutritional reassurance." The emotional JTBD is about feeling competent, not achieving perfect nutrition. A simple signal that says "this is good enough" addresses the emotional need directly without requiring users to become nutrition experts. |
+| **Riskiest Assumption** | A simplified nutrition score (green/yellow/red) will be perceived as credible and reassuring rather than judgmental or oversimplified. If parents see a "yellow" rating and feel judged, the feature increases guilt rather than reducing it. The scoring must feel like reassurance, not evaluation. |
+
+**Hypothesis Statement:**
+> We believe that busy parents will feel significantly less meal-related guilt when meals include a simple nutrition quality signal because the guilt stems from uncertainty about "am I doing enough?" rather than actual nutritional failure, and a credible signal resolves that uncertainty.
+
+---
+
+### Hypothesis 3: The Zero-Planning Pantry Match
+
+**The 4-Field Contract:**
+
+| Field | Details |
+|-------|---------|
+| **Expected Outcome** | Parents using ingredient-aware meal matching (based on pantry contents) will reduce unplanned grocery stops from an average of 2.5 per week to 1 or fewer, saving approximately 40-60 minutes per week of errand time. |
+| **Target Behavior Change** | Parents will stop making "ingredient gap" grocery runs for single missing items. Instead, they'll use meals matched to what they already have, and consolidate remaining needs into a single planned weekly shop. The target is elimination of reactive, unplanned grocery behavior. |
+| **Rationale** | The HC2 observations show 5/8 sessions included unplanned grocery stops, and 3/8 interview subjects cited "ingredient gap" as the reason meal plans fail. Existing meal planning tools fail because they prescribe meals that require specific ingredients parents don't have. Matching meals to available ingredients inverts the model — start from what's in the kitchen, not from what the recipe demands. |
+| **Riskiest Assumption** | Parents can and will accurately report what's in their kitchen. The pantry-matching model depends on knowing pantry contents. If keeping an ingredient inventory is itself a burden (another planning task parents don't have time for), the solution creates the same overhead it's trying to eliminate. |
+
+**Hypothesis Statement:**
+> We believe that busy parents will reduce unplanned grocery trips by 60% when meal suggestions are matched to their current pantry contents because the primary cause of unplanned trips is ingredient gaps between planned meals and available ingredients, not general grocery needs.
+
+---
+
+## 3. Assumption Risk Map
+
+| # | Assumption | Hypothesis | Lethality | Uncertainty | Priority | Validation Status |
+|---|-----------|-----------|-----------|-------------|----------|-------------------|
+| A1 | Parents will trust an automated suggestion enough to act without deliberating | H1 | High | High | Test First | Unvalidated |
+| A2 | A simplified nutrition score will feel reassuring rather than judgmental | H2 | High | High | Test First | Unvalidated |
+| A3 | Parents can accurately maintain a pantry inventory without it becoming a burden | H3 | High | Medium | Test Soon | Unvalidated |
+| A4 | The 5:30 PM moment is the right intervention point (not earlier in the day) | H1 | Medium | Medium | Test Soon | Partially Validated |
+| A5 | "Good enough" nutrition is an acceptable standard (not aspirational perfect nutrition) | H2 | Medium | Low | Monitor | Partially Validated |
+| A6 | Decision fatigue — not lack of cooking skill — is the primary barrier | H1, H3 | High | Low | Monitor | Partially Validated |
+| A7 | Reducing unplanned grocery trips will be perceived as a meaningful benefit | H3 | Medium | Medium | Test Soon | Unvalidated |
+| A8 | Willingness to pay for this type of solution exists in this segment | H1, H2, H3 | High | High | Test First | Unvalidated |
+
+## 4. Recommended Testing Order
+
+| Priority | Assumption | Suggested Method | Minimum Evidence |
+|----------|-----------|-----------------|-----------------|
+| 1 | A1: Parents trust automated suggestions enough to act | Concierge test — manually send personalized dinner suggestions via text to 15-20 parents for 2 weeks, measure action rate | ≥60% act on suggestion without requesting alternatives within the first week; action rate stable or increasing in week 2 |
+| 2 | A8: Willingness to pay exists | Landing page smoke test — "Join the waitlist for $X/month" with pricing tiers, measure sign-up conversion | ≥5% visitor-to-signup conversion with price commitment (not free tier) |
+| 3 | A2: Nutrition score feels reassuring, not judgmental | Prototype test — show nutrition-scored meal cards to 10-12 parents in moderated sessions, measure emotional response | ≥8 of 12 describe feeling "reassured" or "relieved"; <2 of 12 describe feeling "judged" or "shamed" |
+| 4 | A3: Pantry inventory maintenance is not burdensome | Wizard of Oz test — provide a simple pantry tracking tool to 10 parents for 1 week, measure sustained daily use | ≥7 of 10 maintain pantry updates for full 7 days; average daily update time <2 minutes |
+| 5 | A7: Reduced grocery trips perceived as meaningful | User interview — post-concierge-test interview about perceived value of grocery trip reduction | ≥6 of 10 mention time savings from fewer trips unprompted when asked about benefits |
+
+## 5. Flagged Concerns
+
+| Concern | Impact | Recommended Action |
+|---------|--------|-------------------|
+| No data on willingness to pay (A8) — all HC2 research focused on problem, not solution viability | If there's no willingness to pay, all three hypotheses are academically interesting but commercially unviable. This could invalidate the entire hypothesis set regardless of behavioral validation. | Route to Isla 🔍 for targeted user interviews (HC9) — specifically probe willingness to pay and price sensitivity before investing in behavioral experiments. Include question: "What are you currently spending on meal planning shortcuts (apps, meal kits, takeout)?" to establish baseline spend. |
+| Pantry tracking assumption (A3) may introduce a new burden that undermines the value proposition | If pantry tracking requires more than 2 minutes/day, H3 fails and H1's suggestion quality degrades (suggestions won't match available ingredients without accurate pantry data) | Consider testing A3 early — if pantry tracking is too burdensome, pivot H1 and H3 to ingredient-agnostic suggestions. This would weaken the value proposition but remove a dependency. |