convoke-agents 2.0.0

package/_bmad/bme/_vortex/examples/hc5-example-signal-report.md

@@ -0,0 +1,76 @@
+---
+contract: HC5
+type: artifact
+source_agent: noah
+source_workflow: signal-interpretation
+target_agents: [max]
+input_artifacts:
+  - path: "_bmad-output/vortex-artifacts/hc4-decision-eliminator-concierge-2026-02-15.md"
+    contract: HC4
+created: 2026-02-26
+---
+
+# HC5 Signal Report: 5:30 PM Decision Eliminator — Post-Graduation Production Signal
+
+> **This is an example artifact** demonstrating the HC5 schema format. It shows what a real output from Noah's signal-interpretation workflow looks like — a production signal interpreted through experiment lineage with trend analysis, anomaly detection, and data quality assessment. This example continues the "Busy Parents Meal Planning" domain from the HC2 and HC3 examples.
+
+## 1. Signal Description
+
+| Field | Details |
+|-------|---------|
+| **Signal Summary** | Context-aware dinner suggestion feature is driving a 79% action rate among active users, exceeding the 60% experiment threshold, but suggestion requests are clustering 45-90 minutes earlier than the designed 5:30 PM intervention point. |
+| **Signal Type** | Behavior Pattern |
+| **Severity** | Warning |
+| **Detection Method** | Production metric monitoring — daily active usage analytics combined with timestamp analysis of suggestion request patterns over 4-week post-graduation observation period. |
+| **Time Window** | 2026-02-01 to 2026-02-26 (4 weeks post-graduation) |
+| **Affected Scope** | 847 active users across 3 metropolitan areas (San Francisco, Austin, Denver). All user segments affected — both early adopters and general rollout users show the same timing shift. |
+
+## 2. Context
+
+### Experiment Lineage
+
+| Field | Details |
+|-------|---------|
+| **Originating Experiment** | "5:30 PM Decision Eliminator" concierge test — 18 parents received manually curated dinner suggestions via text message for 2 weeks. Reference: `_bmad-output/vortex-artifacts/hc4-decision-eliminator-concierge-2026-02-15.md` |
+| **Original Hypothesis** | 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. (HC3 Hypothesis 1) |
+| **Experiment Outcome** | Confirmed — 14 of 18 participants (78%) acted on suggestions without requesting alternatives within the first week. Action rate increased to 83% in week 2. Average decision time dropped from 18 minutes to 2.4 minutes. |
+| **Expected Production Behavior** | At scale, action rate expected to stabilize between 60-75% (lower than concierge due to algorithm vs. human curation). Decision time expected to remain under 5 minutes for users who act on suggestions. Suggestion timing anchored at 5:30 PM based on experiment finding that 22 of 28 participants described the "5:30 PM panic" moment. |
+| **Actual vs Expected** | Action rate is 79% — exceeding the upper bound of expected range (75%). This is a positive divergence. However, 62% of suggestion requests are occurring between 4:00-4:45 PM rather than at the designed 5:30 PM trigger. Users are proactively opening the app earlier than the push notification is sent. The timing assumption — that 5:30 PM is the critical intervention point — appears partially wrong. |
+
+### Vortex History
+
+| Field | Details |
+|-------|---------|
+| **Problem Definition** | HC2 problem definition: "Busy dual-income parents spend more time deciding what to feed their families than actually preparing meals." Reference: `_bmad-output/vortex-artifacts/hc2-problem-definition-busy-parents-2026-02-23.md` |
+| **Hypothesis Origin** | HC3 hypothesis contract: Hypothesis 1 "The 5:30 PM Decision Eliminator." The riskiest assumption was A1: "Parents will trust an automated suggestion enough to act without deliberating." Reference: `_bmad-output/vortex-artifacts/hc3-hypothesis-contract-busy-parents-2026-02-24.md` |
+| **Previous Signals** | None — this is the first HC5 signal report for this experiment. |
+| **Related Experiments** | HC3 Hypothesis 2 ("Guilt-Free Nutrition Signal") is in prototype testing. HC3 Hypothesis 3 ("Zero-Planning Pantry Match") is in Wizard of Oz testing. Neither has graduated to production yet. |
+
+## 3. Trend Analysis
+
+| Field | Details |
+|-------|---------|
+| **Trend Direction** | Stable (action rate); Improving (early request behavior is increasing) |
+| **Trend Duration** | 4 weeks of observation. Action rate stabilized in week 2 at 78-80%. Early request pattern emerged in week 2 and has increased from 48% to 62% of total requests over weeks 2-4. |
+| **Rate of Change** | Action rate: +1% week-over-week (stabilizing). Early request percentage: +4.7% week-over-week (growing). Average suggestion-to-action time: 2.8 minutes (stable, well within 5-minute threshold). |
+| **Baseline Comparison** | Experiment baseline: 78% action rate at 5:30 PM push notification. Production: 79% action rate but 62% of interactions are user-initiated before the push notification fires. The core metric (action rate) is tracking positively. The timing pattern is a divergence from the designed intervention model. |
+| **Confidence** | High — 847 active users over 4 weeks provides sufficient sample size. Data collection is complete with no gaps. The early request pattern is statistically significant (p < 0.01 compared to expected 5:30 PM clustering). |
+
+## 4. Anomaly Detection
+
+| Field | Details |
+|-------|---------|
+| **Anomaly Description** | Users are proactively requesting dinner suggestions between 4:00-4:45 PM — approximately 45-90 minutes before the designed 5:30 PM push notification. This behavior was not observed in the concierge experiment, where participants received suggestions at 5:30 PM and responded to them. In production, users are seeking the suggestion before it arrives. |
+| **Deviation from Expected** | The experiment validated that 5:30 PM is the "panic moment" based on 22 of 28 research participants. Production data shows users want the decision eliminated earlier — possibly during their commute or during afternoon planning rather than at the moment of kitchen arrival. The functional need (eliminate dinner decision) is confirmed, but the optimal timing assumption (5:30 PM) appears to be 45-90 minutes late. |
+| **Potential Explanations** | (1) The concierge experiment delivered suggestions at 5:30 PM by design, so participants never had the option to request earlier — the timing preference was untestable in the experiment format. (2) Production users may be planning ahead during commute time (4:00-4:30 PM) rather than waiting until kitchen arrival. (3) The 5:30 PM "panic" identified in research may describe when stress peaks, not when users want the solution delivered — there may be a preparation window before the panic moment. |
+| **Discovery Needed** | Yes |
+| **Discovery Focus** | Route to Isla for targeted user research on preferred suggestion timing. Key questions: (1) Why are users opening the app at 4:00-4:45 PM? What are they doing at that moment? (2) Is earlier delivery (during commute) actually preferred, or are users checking preemptively out of anxiety? (3) Would adaptive timing (learn each user's preferred request time) increase action rates further? (4) Does the early request pattern differ between user segments (e.g., remote workers vs. commuters)? |
+
+## 5. Data Quality
+
+| Field | Details |
+|-------|---------|
+| **Sample Size** | 847 active users generating 18,412 suggestion interactions over 4 weeks (average 5.4 interactions per user per week). |
+| **Data Completeness** | Complete — all user interactions are logged with timestamps, action taken (yes/no/modified), and time-to-action. No data gaps during the observation period. One 4-hour logging outage on 2026-02-12 affected approximately 200 interactions; these were excluded from timing analysis but included in action rate calculations. |
+| **Known Biases** | Early adopter bias — the first 4 weeks of production data skew toward users who actively sought out the feature. General rollout users (weeks 3-4) show similar action rates but slightly lower early-request behavior (55% vs. 68% for early adopters), suggesting the timing anomaly is real but may be slightly amplified by enthusiast behavior. |
+| **Confidence Level** | High — sufficient sample size, near-complete data, identified biases are minor and documented. The core finding (action rate exceeding baseline) is robust. The timing anomaly finding is directionally strong but would benefit from Isla's qualitative research to understand user intent behind the timing shift. |

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

@@ -0,0 +1,232 @@
+# Emma User Guide - Contextualization Expert 🎯
+
+**Agent:** Emma (contextualization-expert)
+**Version:** 1.6.4
+**Module:** Convoke (bme) - Vortex Pattern
+**Last Updated:** 2026-03-02
+
+---
+
+## Quick Start
+
+**Who is Emma?**
+Emma is a Contextualization Expert who helps teams establish strategic context before diving into solutions. She guides you through the "Contextualize" stream of the Vortex pattern — creating lean personas focused on jobs-to-be-done, defining product vision with strategic clarity, and deciding which problem space to investigate.
+
+**When to use Emma:**
+- Creating lean user personas focused on jobs-to-be-done (not demographics)
+- Defining product vision and strategic scope
+- Deciding which problem space to investigate and setting boundaries
+- Challenging assumptions before building
+- Aligning teams around the "why" before the "what"
+- Validating existing personas and vision documents for completeness
+
+**Emma vs. Isla — which agent do I need?**
+
+| | Emma 🎯 (Contextualize) | Isla 🔍 (Empathize) |
+|---|---|---|
+| **When** | Before research — you need strategic context | During research — you need to understand users deeply |
+| **Input** | Business context, market landscape, strategic goals | Real users, interview data, observations |
+| **Output** | Lean personas, product vision, problem scope | Empathy maps, interview findings, discovery research |
+| **Focus** | What is the landscape? (strategy-based) | Who are the users? (evidence-based) |
+
+**Decision aid:** If you need to define the strategic context, create lean personas, or set product vision before research begins → **Emma**. If you have access to real users and need to understand them deeply → **Isla**.
+
+**What you'll get:**
+Lean personas focused on jobs-to-be-done and problem contexts, product vision documents with strategic clarity, and problem scope definitions with clear boundaries and assumption identification.
+
+---
+
+## How to Invoke Emma
+
+### Method 1: Direct Agent File Reading (Recommended)
+
+Read Emma's agent file to activate her. This works in any environment:
+
+**Claude Code:**
+```
+Read the file at _bmad/bme/_vortex/agents/contextualization-expert.md
+```
+
+**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: Slash Command (BMAD Environments Only)
+
+If your environment supports BMAD slash commands:
+
+```
+/bmad-agent-bme-contextualization-expert
+```
+
+---
+
+## Emma's Menu Options
+
+Once Emma activates, you'll see menu options for her available workflows:
+
+```
+1. [MH] Redisplay Menu Help
+2. [CH] Chat with Emma about contextualization, lean personas, or product vision
+3. [LP] Create Lean Persona: Rapid user persona in 6 steps
+4. [PV] Define Product Vision: Strategic vision and scope in 6 steps
+5. [CS] Contextualize Scope: Decide which problem space to investigate
+6. [VL] Validate Context: Review existing personas/vision for completeness
+7. [PM] Start Party Mode
+8. [DA] Dismiss Agent
+```
+
+### How to Select an Option
+
+1. **Number:** Type `3` to select option 3
+2. **Command Code:** Type `LP` to create a lean persona
+3. **Fuzzy Match:** Type `persona` or `vision` or `scope` - Emma will match the command
+
+---
+
+## Workflows
+
+### [LP] Create Lean Persona
+
+Create lean user personas focused on jobs-to-be-done and problem contexts — not demographics. Lean personas are lightweight, actionable, and designed to guide decisions rather than collect fictional details.
+
+**Output:** `{output_folder}/vortex-artifacts/lean-persona-{name}-{date}.md`
+**Time:** 30-60 minutes
+
+**When to use Lean Persona:**
+You're starting a new product initiative and need to define who you're building for. You want to focus on what job the user is hiring your product to do, not their age, gender, or fictional backstory.
+
+---
+
+### [PV] Define Product Vision
+
+Define product vision and scope with strategic clarity. A product vision anchors all downstream work — from research to experimentation to production. Without it, teams build features instead of solving problems.
+
+**Output:** `{output_folder}/vortex-artifacts/product-vision-{date}.md`
+**Time:** 45-90 minutes
+
+**When to use Product Vision:**
+You need to align the team around the "why" before debating the "what." A clear product vision prevents feature bloat, scope creep, and misaligned execution.
+
+---
+
+### [CS] Contextualize Scope
+
+Decide which problem space to investigate and define boundaries. Scope contextualization prevents teams from boiling the ocean — it forces a deliberate choice about which problem deserves focus.
+
+**Output:** `{output_folder}/vortex-artifacts/problem-scope-{date}.md`
+**Time:** 30-60 minutes
+
+**When to use Contextualize Scope:**
+You have multiple possible problem areas and need to decide which one to investigate first. Or you have a broad problem and need to draw boundaries around a manageable scope.
+
+---
+
+### [VL] Validate Context
+
+Review existing personas, vision documents, and scope definitions for completeness and strategic coherence.
+
+**When to use Validate Context:**
+- You created a persona or vision document and want expert review
+- You inherited artifacts from another team
+- Your understanding has changed and you need to update
+- You're preparing to hand off to Isla for user research
+
+**What Emma checks:**
+- Are personas focused on jobs-to-be-done (not demographics)?
+- Is the product vision specific enough to guide decisions?
+- Are scope boundaries clear and assumptions identified?
+- Are insights backed by strategic rationale?
+
+---
+
+## Emma's Philosophy: Context Before Solutions
+
+### The Contextualize Stream (Vortex Pattern)
+
+Emma guides teams through the "Contextualize" stream (Stream 1):
+- **Context before solutions** — know WHO and WHY before building WHAT
+- **Lean personas over heavy empathy maps** — just enough detail to guide decisions
+- **Product vision anchors all downstream work** — clarity drives alignment
+- **The right problem is more valuable than the perfect solution**
+- **Scope boundaries are as important as scope definitions**
+
+---
+
+## Chatting with Emma (CH)
+
+Select **[CH] Chat** to discuss:
+- Lean Startup methodologies and strategic framing
+- Jobs-to-be-Done framework and lean personas
+- Product vision and strategic alignment
+- Problem-product space navigation
+- Assumption identification and validation
+- Contextualization strategies
+
+**Example questions:**
+- "How do I validate assumptions before building?"
+- "What's the difference between problem-solution fit and product-market fit?"
+- "How do I define a problem space?"
+- "What makes a good lean persona vs. a traditional persona?"
+- "How do I write a product vision that actually guides decisions?"
+- "When should I hand off to Isla for user research?"
+
+---
+
+## 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: "Unknown skill: bmad-agent-bme-contextualization-expert"
+
+**What it means:**
+Slash commands aren't available in your environment.
+
+**How to fix:**
+Use Method 2 (Direct Agent File Reading) instead:
+
+1. Read the file: `_bmad/bme/_vortex/agents/contextualization-expert.md`
+2. Emma will activate normally
+3. This method works in all environments
+
+---
+
+## Tips from Emma
+
+### "Context before solutions"
+Before you debate features, align on who you're building for and why it matters. A clear strategic context prevents wasted execution effort and keeps teams focused on the right problems.
+
+### "Personas over demographics"
+Age, gender, and income don't drive behavior — jobs-to-be-done and context do. Instead of "millennials," ask "what job are they hiring your product to do?"
+
+### "Vision before features"
+Align your team around the "why" before you debate the "what." A clear product vision prevents feature bloat and scope creep.
+
+### "Problem-solution fit comes first"
+Before you find product-market fit, validate problem-solution fit. Are you solving a real problem? For the right people? In the right context?
+
+### "Clarity is kindness"
+Unclear product strategy wastes everyone's time. Be specific about problem spaces, target users, and success criteria. Clarity accelerates execution.
+
+---
+
+## Credits
+
+**Agent:** Emma (contextualization-expert)
+**Module:** Convoke (bme)
+**Submodule:** Vortex Pattern (`_vortex`)
+**Stream:** Contextualize (Stream 1)
+**Version:** 1.6.4
+
+---
+
+**Questions?** Chat with Emma (CH) - she's here to help you contextualize your product strategy! 🎯

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

@@ -0,0 +1,208 @@
+# Isla User Guide - Discovery & Empathy Expert 🔍
+
+**Agent:** Isla (discovery-empathy-expert)
+**Version:** 1.5.0
+**Module:** Convoke (bme) - Vortex Pattern
+**Last Updated:** 2026-02-20
+
+---
+
+## Quick Start
+
+**Who is Isla?**
+Isla is a qualitative research expert who helps teams deeply understand their users through structured discovery and empathy work. She guides you through the "Empathize" stream of the Vortex pattern — user interviews, empathy mapping, and discovery research.
+
+**When to use Isla:**
+- Understanding users before defining problems
+- Designing and conducting user interviews
+- Creating evidence-based empathy maps
+- Planning discovery research activities
+- Synthesizing qualitative research findings
+- Validating assumptions about user needs and behaviors
+
+**What you'll get:**
+Empathy maps grounded in research, interview guides and findings, discovery research plans and synthesis documents.
+
+---
+
+## How to Invoke Isla
+
+### Method 1: Direct Agent File Reading (Recommended)
+
+Read Isla's agent file to activate her. This works in any environment:
+
+**Claude Code:**
+```
+Read the file at _bmad/bme/_vortex/agents/discovery-empathy-expert.md
+```
+
+**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: Slash Command (BMAD Environments Only)
+
+If your environment supports BMAD slash commands:
+
+```
+/bmad-agent-bme-discovery-empathy-expert
+```
+
+---
+
+## Isla's Menu Options
+
+Once Isla activates, you'll see menu options for her available workflows:
+
+```
+1. [MH] Redisplay Menu Help
+2. [CH] Chat with Isla about user research, empathy, and discovery
+3. [EM] Empathy Map: Create structured empathy maps (Says/Thinks/Does/Feels)
+4. [UI] User Interview: Design interview scripts and capture findings
+5. [UD] User Discovery: Plan and execute broader discovery research
+6. [VE] Validate: Review empathy maps and research artifacts
+7. [PM] Start Party Mode
+8. [DA] Dismiss Agent
+```
+
+### How to Select an Option
+
+1. **Number:** Type `3` to select option 3
+2. **Command Code:** Type `EM` to create an empathy map
+3. **Fuzzy Match:** Type `empathy` or `interview` - Isla will match the command
+
+---
+
+## Workflows
+
+### [EM] Empathy Map (6 steps)
+
+Create comprehensive empathy maps for target users through structured exploration.
+
+**Steps:**
+1. Define Target User
+2. Says & Thinks
+3. Does & Feels
+4. Pain Points
+5. Gains
+6. Synthesize
+
+**Output:** `{output_folder}/empathy-map-{user-name}-{date}.md`
+**Time:** 30-60 minutes
+
+---
+
+### [UI] User Interview (6 steps)
+
+Design interview scripts, plan participant recruitment, and capture findings.
+
+**Steps:**
+1. Define Research Goals
+2. Design Interview Script
+3. Plan Participant Recruitment
+4. Conduct Interviews (guidance)
+5. Capture Findings
+6. Synthesize Insights
+
+**Output:** `{output_folder}/user-interview-{topic}-{date}.md`
+**Time:** 45-90 minutes (planning), plus interview time
+
+---
+
+### [UD] User Discovery (6 steps)
+
+Plan and execute broader discovery research beyond interviews.
+
+**Steps:**
+1. Define Discovery Scope
+2. Choose Research Methods
+3. Plan Research Activities
+4. Execute Research (guidance)
+5. Organize Raw Data
+6. Synthesize Discovery Findings
+
+**Output:** `{output_folder}/user-discovery-{topic}-{date}.md`
+**Time:** 60-120 minutes (planning), plus research time
+
+---
+
+## Isla's Philosophy: Listen Before You Define
+
+### The Empathize Stream (Vortex Pattern)
+
+Isla guides teams through the "Empathize" stream:
+- **Listen before you define** - Understand the problem from the user's perspective first
+- **Observe before you assume** - Watch what people do, not just what they say
+- **Feelings are data** - Emotional responses reveal unmet needs
+- **Talk to real people, not personas** - Personas come after research, not before
+- **The messier the research, the richer the insights** - Embrace ambiguity
+
+---
+
+## Chatting with Isla (CH)
+
+Select **[CH] Chat** to discuss:
+- Qualitative research methods
+- Interview technique and question design
+- Empathy mapping best practices
+- User observation and ethnographic methods
+- Research synthesis and pattern recognition
+- When to use which research method
+
+**Example questions:**
+- "How do I avoid leading questions in interviews?"
+- "When should I use empathy mapping vs. user interviews?"
+- "How many users do I need to talk to?"
+- "How do I synthesize findings from multiple interviews?"
+
+---
+
+## 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 discovery 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 Isla
+
+### "The best interviews feel like conversations"
+Your script is a guide, not a rigid questionnaire. Follow the participant's energy and probe where they show emotion or hesitation.
+
+### "Ask about the past, not the future"
+"Tell me about the last time you..." produces better insights than "Would you ever...?" People are terrible at predicting their own behavior.
+
+### "Silence is your most powerful tool"
+When you stop talking, people fill the silence with their real thoughts. Resist the urge to fill every pause.
+
+### "Feelings are data"
+When a participant's voice changes, they lean forward, or they hesitate — that's where the real insight lives. Note the emotion, not just the words.
+
+---
+
+## Credits
+
+**Agent:** Isla (discovery-empathy-expert)
+**Module:** Convoke (bme)
+**Submodule:** Vortex Pattern (`_vortex`)
+**Stream:** Empathize (Stream 2)
+**Version:** 1.5.0
+
+---
+
+**Questions?** Chat with Isla (CH) - she's here to help you understand your users! 🔍