convoke-agents 2.0.0

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

@@ -0,0 +1,235 @@
+# Mila User Guide - Research Convergence Specialist 🔬
+
+**Agent:** Mila (research-convergence-specialist)
+**Version:** 1.6.0
+**Module:** Convoke (bme) - Vortex Pattern
+**Last Updated:** 2026-02-25
+
+---
+
+## Quick Start
+
+**Who is Mila?**
+Mila is a Research Convergence and Problem Definition Specialist who helps teams synthesize divergent research findings into actionable problem definitions. She guides you through the "Synthesize" stream of the Vortex pattern — converging multiple research artifacts into Jobs-to-be-Done framing, Pains & Gains analysis, and evidence-backed problem statements.
+
+**When to use Mila:**
+- Synthesizing multiple research artifacts into a single problem definition
+- Framing core Jobs-to-be-Done from research evidence
+- Conducting Pains & Gains analysis grounded in artifact data
+- Mapping cross-source patterns across different research streams
+- Re-synthesizing a problem definition after a failed experiment (pivot scenario)
+- Validating whether research artifacts converge before committing to problem definition
+
+**Mila vs. Emma — which agent do I need?**
+
+| | Mila 🔬 (Synthesize) | Emma 🎯 (Contextualize) |
+|---|---|---|
+| **When** | After research — you have artifacts to synthesize | Before research — you need strategic context |
+| **Input** | HC1 empathy artifacts + any research | Business context, market landscape, strategic goals |
+| **Output** | HC2 problem definition (JTBD + Pains & Gains) | Contextualization document (strategic framing) |
+| **Focus** | What is the problem? (evidence-based) | What is the landscape? (strategy-based) |
+
+**Decision aid:** If you have research artifacts and need to define the problem → **Mila**. If you need to understand the broader context before research begins → **Emma**.
+
+**What you'll get:**
+Evidence-backed problem definitions (HC2 artifacts) grounded in Jobs-to-be-Done framing and Pains & Gains analysis, or pattern analysis documents mapping cross-source convergence.
+
+---
+
+## How to Invoke Mila
+
+### Method 1: Direct Agent File Reading (Recommended)
+
+Read Mila's agent file to activate her. This works in any environment:
+
+**Claude Code:**
+```
+Read the file at _bmad/bme/_vortex/agents/research-convergence-specialist.md
+```
+
+**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: Slash Command (BMAD Environments Only)
+
+If your environment supports BMAD slash commands:
+
+```
+/bmad-agent-bme-research-convergence-specialist
+```
+
+---
+
+## Mila's Menu Options
+
+Once Mila activates, you'll see menu options for her available workflows:
+
+```
+1. [MH] Redisplay Menu Help
+2. [CH] Chat with Mila about research convergence, problem definition, JTBD, or synthesis
+3. [RC] Research Convergence: Synthesize divergent research into a single problem definition
+4. [PR] Pivot Resynthesis: Re-synthesize problem definition after failed experiments
+5. [PA] Pattern Mapping: Map cross-source patterns across research artifacts
+6. [PM] Start Party Mode
+7. [DA] Dismiss Agent
+```
+
+### How to Select an Option
+
+1. **Number:** Type `3` to select option 3
+2. **Command Code:** Type `RC` to start research convergence
+3. **Fuzzy Match:** Type `convergence` or `pattern` - Mila will match the command
+
+---
+
+## Workflows
+
+### [RC] Research Convergence (5 steps)
+
+Synthesize divergent research findings into a single, actionable problem definition grounded in Jobs-to-be-Done framing and Pains & Gains analysis.
+
+**Steps:**
+1. Setup & Input Validation
+2. Context Loading & Analysis
+3. Jobs-to-be-Done Framing
+4. Pains & Gains Analysis
+5. Synthesize & Route
+
+**Output:** `{output_folder}/vortex-artifacts/hc2-problem-definition-{date}.md`
+**Time:** 60-120 minutes
+
+---
+
+### [PR] Pivot Resynthesis (5 steps)
+
+Re-synthesize a problem definition after a failed experiment. When Max says "pivot," Mila takes the original research plus new evidence from the failed experiment and produces a revised problem definition.
+
+**Steps:**
+1. Setup & Input Validation
+2. Context Loading & Analysis
+3. JTBD Re-Framing
+4. Pains & Gains Revision
+5. Synthesize & Route
+
+**Output:** `{output_folder}/vortex-artifacts/hc2-problem-definition-{date}.md`
+**Time:** 45-90 minutes
+
+**The Pivot Scenario (Journey 5):**
+1. Mila produces an HC2 problem definition via research-convergence
+2. Liam generates hypotheses from the HC2 → produces HC3 hypothesis contracts
+3. Wade tests hypotheses → produces HC4 experiment context
+4. Max evaluates results → determines the experiment failed and says "pivot"
+5. Mila re-enters via pivot-resynthesis: takes original HC1 artifacts + HC4 experiment evidence → produces a revised HC2
+6. The revised HC2 goes back to Liam for new hypotheses
+
+**How it differs from Research Convergence:**
+- **Research Convergence** creates a new HC2 from scratch using research artifacts
+- **Pivot Resynthesis** revises an existing HC2 incorporating evidence from a failed experiment — it builds on what was learned, not starting over
+
+---
+
+### [PA] Pattern Mapping (5 steps)
+
+Map cross-source patterns across multiple research artifacts to identify convergent themes before committing to a full problem definition.
+
+**Steps:**
+1. Setup & Input Validation
+2. Context Loading & Analysis
+3. Pattern Identification
+4. Theme Clustering
+5. Synthesize & Route
+
+**Output:** `{output_folder}/vortex-artifacts/pattern-analysis-{date}.md`
+**Time:** 30-60 minutes
+
+**When to use Pattern Mapping vs. Research Convergence:**
+- **Pattern Mapping** is reconnaissance — identify what patterns exist before committing
+- **Research Convergence** is commitment — produce the full problem definition
+
+Use pattern mapping when you want to see if your research converges before investing in full JTBD framing and Pains & Gains analysis. Once patterns are clear, run research-convergence.
+
+---
+
+## Mila's Philosophy: Convergence Before Definition
+
+### The Synthesize Stream (Vortex Pattern)
+
+Mila guides teams through the "Synthesize" stream:
+- **Convergence over collection** - synthesize before you define
+- **Jobs-to-be-Done framing** turns observations into actionable problem statements
+- **Pains & Gains analysis** reveals what users value vs. what they tolerate
+- **Cross-source triangulation** — one data point is an anecdote, three are a pattern
+- **Problem definition is the highest-leverage activity** in product discovery
+
+---
+
+## Chatting with Mila (CH)
+
+Select **[CH] Chat** to discuss:
+- Research synthesis and convergence methods
+- Jobs-to-be-Done framing techniques
+- Pains & Gains analysis approaches
+- Cross-source pattern identification
+- Problem definition best practices
+- When to use which Mila workflow
+
+**Example questions:**
+- "How do I frame a good JTBD statement?"
+- "When should I use pattern mapping vs. full convergence?"
+- "How many artifacts do I need for strong convergence?"
+- "What if my research contradicts itself?"
+- "How do I know when my problem definition is strong enough for Liam?"
+- "What's the difference between a pain and a gain in this framework?"
+
+---
+
+## Troubleshooting
+
+### Error: "Configuration Error: Cannot load config file"
+
+**How to fix:**
+1. Check if `_bmad/bme/_vortex/config.yaml` exists
+2. If missing: `npx convoke-install-vortex`
+
+### Error: "Cannot load synthesis workflow"
+
+**How to fix:**
+1. Check workflow files exist in `_bmad/bme/_vortex/workflows/`
+2. Run `npx convoke-doctor` to diagnose
+3. If missing: `npx convoke-install-vortex`
+
+---
+
+## Tips from Mila
+
+### "The best problem definitions feel inevitable"
+When your problem statement follows naturally from the research — when it feels like the obvious conclusion rather than a surprise — that's convergence working. If the problem statement feels forced, you may need more evidence or a different framing.
+
+### "Don't synthesize too early"
+The data shows that rushing to problem definition before you have enough research leads to weak, assumption-heavy statements. If you have fewer than 2 artifacts with converging insights, consider running Isla's workflows first to deepen your evidence base.
+
+### "Contradictions are data, not failures"
+When your artifacts disagree, that's not a sign that your research is broken. Contradictions often reveal that you're looking at different user segments or that the problem is more nuanced than expected. Document them honestly — they make your problem definition stronger.
+
+### "One data point is an anecdote, three are a pattern"
+A single interview quote is interesting. The same insight appearing across three different research artifacts is a signal worth acting on. Cross-source triangulation is how you build confidence in your problem definition.
+
+---
+
+## Credits
+
+**Agent:** Mila (research-convergence-specialist)
+**Module:** Convoke (bme)
+**Submodule:** Vortex Pattern (`_vortex`)
+**Stream:** Synthesize (Stream 3)
+**Version:** 1.6.0
+
+---
+
+**Questions?** Chat with Mila (CH) - she's here to help you converge your research into actionable problem definitions! 🔬

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

@@ -0,0 +1,258 @@
+# Noah User Guide - Production Intelligence Specialist 📡
+
+**Agent:** Noah (production-intelligence-specialist)
+**Version:** 1.6.0
+**Module:** Convoke (bme) - Vortex Pattern
+**Last Updated:** 2026-02-26
+
+---
+
+## Quick Start
+
+**Who is Noah?**
+Noah is a Production Intelligence Specialist who interprets production signals through experiment lineage and Vortex history. He guides you through the "Sensitize" stream of the Vortex pattern — reading what real-world usage reveals about product-market fit across signal interpretation, behavioral pattern detection, and portfolio-level production monitoring. Noah produces intelligence — contextual, evidence-based signal reports. He does not produce strategy or recommendations; that is Max's domain.
+
+**When to use Noah:**
+- Interpreting a production signal through the lens of the experiment that created it
+- Classifying observed behavior patterns against validated experiment baselines (expected variance, regression, or novel behavior)
+- Monitoring multiple graduated experiments in production simultaneously at portfolio scale
+- Detecting anomalous user behavior that experiments didn't predict
+- Bridging production data back to Vortex experiment history (HC4 → HC5)
+- Identifying cross-experiment patterns that single-signal analysis misses
+- Prioritizing which experiments need attention based on divergence severity
+
+**Noah vs. Raw Dashboards/Analytics — which do I need?**
+
+| | Noah 📡 (Sensitize) | Raw Dashboards/Analytics |
+|---|---|---|
+| **When** | After experiments — you have production data to interpret through experiment context | Anytime — you need to see raw metrics |
+| **Input** | HC4 experiment context + production signals | Metrics / analytics tools |
+| **Output** | HC5 signal reports (contextualized intelligence) | Numbers, charts, alerts |
+| **Focus** | What does this signal mean given the experiment? (signal + context + trend) | What are the numbers? (raw metrics) |
+| **Value** | Connects production reality to experiment predictions — surfaces what dashboards hide | Shows current state without experiment context |
+
+**Decision aid:** If you have production data and need to understand what it means in context of your experiments → **Noah**. If you just need to see the numbers → dashboards. Noah turns dashboard readings into experiment-grounded intelligence.
+
+**What you'll get:**
+HC5 signal reports — contextualized intelligence reports that interpret production signals through experiment lineage, assess trends against validated baselines, flag anomalies for discovery research, and provide Max with everything needed for portfolio-level decisions. Signal + context + trend: that's the deliverable.
+
+---
+
+## How to Invoke Noah
+
+### Method 1: Direct Agent File Reading (Recommended)
+
+Read Noah's agent file to activate him. This works in any environment:
+
+**Claude Code:**
+```
+Read the file at _bmad/bme/_vortex/agents/production-intelligence-specialist.md
+```
+
+**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: Slash Command (BMAD Environments Only)
+
+If your environment supports BMAD slash commands:
+
+```
+/bmad-agent-bme-production-intelligence-specialist
+```
+
+---
+
+## Noah's Menu Options
+
+Once Noah activates, you'll see menu options for his available workflows:
+
+```
+1. [MH] Redisplay Menu Help
+2. [CH] Chat with Noah about signal interpretation, anomaly detection, or production monitoring
+3. [SI] Signal Interpretation: Interpret production signals through experiment lineage and Vortex history
+4. [BA] Behavior Analysis: Analyze behavior patterns against validated experiment baselines
+5. [MO] Production Monitoring: Monitor multiple production signals across active experiments
+6. [PM] Start Party Mode
+7. [DA] Dismiss Agent
+```
+
+### How to Select an Option
+
+1. **Number:** Type `3` to select option 3
+2. **Command Code:** Type `SI` to start signal interpretation
+3. **Fuzzy Match:** Type `signal` or `behavior` or `monitoring` - Noah will match the command
+
+---
+
+## Workflows
+
+### [SI] Signal Interpretation (5 steps)
+
+Interpret a single production signal through the experiment that created it. Takes an HC4 experiment context (from Wade) and a production signal, then produces a contextualized HC5 signal report connecting observed production behavior to experiment predictions and Vortex history.
+
+**Steps:**
+1. Setup & Input Validation
+2. Context Loading
+3. Signal Analysis
+4. Anomaly Detection
+5. Synthesize & Route
+
+**Output:** `{output_folder}/vortex-artifacts/hc5-signal-report-{date}.md`
+**Time:** 45-90 minutes
+
+**When to use Signal Interpretation:**
+You have a specific production signal — a metric that moved, a threshold that was breached, a trend that shifted — and you need to understand what it means in context of the experiment that led to this production state. The signal indicates something very different depending on what was tested and what was expected.
+
+---
+
+### [BA] Behavior Analysis (5 steps)
+
+Classify an observed behavior pattern against validated experiment baselines. Takes an HC4 experiment context and an observed behavior, then classifies it as expected variance, regression, or novel behavior — and produces a behavioral HC5 signal report.
+
+**Steps:**
+1. Setup & Input Validation
+2. Context & Baseline Extraction
+3. Behavior Classification
+4. Evidence Gathering
+5. Synthesize & Route
+
+**Output:** `{output_folder}/vortex-artifacts/hc5-behavioral-report-{date}.md`
+**Time:** 60-120 minutes
+
+**The 3 Behavior Categories:**
+- **Expected Variance** — Production behavior falls within experiment-predicted tolerance. The experiment predicted this range and production is confirming it. A valid finding that confirms the experiment model.
+- **Regression** — Behavior diverges negatively from validated experiment performance. Something that worked in the experiment is underperforming in production. Warrants Max's attention for strategic decision.
+- **Novel Behavior** — Behavior not covered by the original experiment hypothesis. Users are doing something the experiment didn't predict. Often the most valuable finding — reveals user intent the hypothesis didn't anticipate. Warrants Isla's discovery investigation.
+
+---
+
+### [MO] Production Monitoring (5 steps)
+
+Monitor production signals across multiple graduated experiments simultaneously. Takes multiple HC4 experiment contexts (portfolio), monitors each experiment's signals against its baselines, prioritizes by divergence severity using the P1/P2/P3 framework, and produces a portfolio-level HC5 signal report.
+
+**Steps:**
+1. Setup & Multi-Experiment Input Validation
+2. Portfolio Assembly & Baseline Mapping
+3. Signal Monitoring & Divergence Assessment
+4. Signal Prioritization & Anomaly Flagging
+5. Synthesize & Route
+
+**Output:** `{output_folder}/vortex-artifacts/hc5-portfolio-report-{date}.md`
+**Time:** 90-180 minutes
+
+**The P1/P2/P3 Prioritization Framework:**
+- **P1 (Immediate)** — Critical divergence + wide scope + high confidence. This experiment needs Max's attention now.
+- **P2 (Attention)** — Warning-level divergence OR wide scope with medium confidence. This experiment should be on Max's radar.
+- **P3 (Monitor)** — Informational divergence OR narrow scope OR low confidence. Continue monitoring, no urgent action.
+
+**When to use Production Monitoring vs. Signal Interpretation:**
+- **Signal Interpretation** analyzes a single signal from a single experiment — depth over breadth
+- **Production Monitoring** monitors signals across multiple experiments simultaneously — breadth over depth, with prioritization to tell Max which experiments need attention first
+
+---
+
+### Anomaly Detection → Isla Routing
+
+All 3 of Noah's workflows can detect anomalous behavior — production patterns that the original experiment didn't predict or account for. When this happens, the Vortex Compass suggests routing to Isla for discovery research:
+
+- **Signal Interpretation:** If the signal reveals behavior not covered by the original hypothesis → Compass suggests Isla 🔍 `user-discovery`
+- **Behavior Analysis:** If the behavior is classified as "novel behavior" → Compass suggests Isla 🔍 `user-discovery`
+- **Production Monitoring:** If anomalies are flagged across one or more experiments → Compass suggests Isla 🔍 `user-discovery`
+
+**Why route to Isla?** Noah observes and reports what production data shows. When that data reveals unexpected user intent — behavior the experiment didn't anticipate — that's a discovery opportunity. Isla investigates the "why" behind the anomaly through qualitative research. Noah detects; Isla discovers.
+
+**What it looks like in the Compass:**
+
+```
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| ⚡ Anomalous behavior detected | user-discovery | Isla 🔍 | Unexpected behavior warrants discovery research (HC10) |
+```
+
+---
+
+## Noah's Philosophy: Signal + Context + Trend
+
+### The Sensitize Stream (Vortex Pattern)
+
+Noah guides teams through the "Sensitize" stream (Stream 6):
+- **Signal + context + trend** — raw metrics mean nothing without interpretation frames
+- **Behavioral patterns reveal intent that surveys miss** — observe what users do, not what they say
+- **Production data is the most honest user feedback** — it can't lie
+- **Anomaly detection surfaces what dashboards hide** — look for what doesn't fit
+- **Observe and report, don't prescribe** — strategic decisions belong downstream
+
+---
+
+## Chatting with Noah (CH)
+
+Select **[CH] Chat** to discuss:
+- Production signal interpretation and experiment lineage
+- Behavioral pattern classification (expected variance / regression / novel)
+- Portfolio-level monitoring and the P1/P2/P3 prioritization framework
+- Anomaly detection and when to route to Isla
+- HC5 signal report structure and content
+- When to use which Noah workflow
+
+**Example questions:**
+- "What does this production signal mean in context of my experiment?"
+- "How do I classify this behavior — is it expected variance or regression?"
+- "When should I use signal-interpretation vs. behavior-analysis vs. production-monitoring?"
+- "I'm seeing unexpected user behavior in production. Is this an anomaly worth investigating?"
+- "How do I set up baselines for portfolio monitoring?"
+- "What's the difference between a metric deviation and a trend shift?"
+- "How do I know when a signal is strong enough for Max to act on?"
+- "My production signals are contradicting my experiment predictions. What should I look for?"
+
+---
+
+## Troubleshooting
+
+### Error: "Configuration Error: Cannot load config file"
+
+**How to fix:**
+1. Check if `_bmad/bme/_vortex/config.yaml` exists
+2. If missing: `npx convoke-install-vortex`
+
+### Error: "Workflow Error: Cannot load signal interpretation workflow"
+
+**How to fix:**
+1. Check workflow files exist in `_bmad/bme/_vortex/workflows/`
+2. Run `npx convoke-doctor` to diagnose
+3. If missing: `npx convoke-install-vortex`
+
+---
+
+## Tips from Noah
+
+### "The signal indicates something — the question is what"
+A production metric moving 15% isn't inherently good or bad. It depends entirely on what the experiment predicted. If the experiment expected a 20% improvement and you're seeing 15%, that's underperformance — even though the metric went up. Context turns numbers into intelligence.
+
+### "Anomalies are the most valuable signals"
+Expected behavior confirms your experiment model worked. That's good. But unexpected behavior — users doing something you didn't predict — tells you something your hypothesis missed. Novel behavior patterns often reveal user intent that surveys and experiments can't capture. Don't dismiss them; route them to Isla.
+
+### "Portfolio monitoring beats single-signal analysis at scale"
+When you're running multiple experiments in production, monitoring them individually misses cross-experiment patterns. Correlated divergence, shared impact areas, contradictory signals between experiments — these surface only when you look at the portfolio as a whole. Use production-monitoring when you have 2+ active experiments.
+
+### "Intelligence, not strategy — that's the boundary"
+Noah produces prioritized, evidence-based signal reports. Noah does not tell you what to do about those signals. That distinction matters. When you see a signal report, your next step is Max — he makes the strategic decisions. Noah's job is to make sure Max has everything needed to decide well.
+
+---
+
+## Credits
+
+**Agent:** Noah (production-intelligence-specialist)
+**Module:** Convoke (bme)
+**Submodule:** Vortex Pattern (`_vortex`)
+**Stream:** Sensitize (Stream 6)
+**Version:** 1.6.0
+
+---
+
+**Questions?** Chat with Noah (CH) — he'll help you read what your production signals are telling you in context. 📡