convoke-agents 2.0.0

package/_bmad/bme/_vortex/workflows/user-discovery/user-discovery.template.md

@@ -0,0 +1,231 @@
+---
+title: "User Discovery: {topic}"
+date: {date}
+created-by: {user-name} with Isla (discovery-empathy-expert)
+status: DRAFT
+---
+
+# User Discovery: {topic}
+
+## Executive Summary
+
+**Discovery Goal:**
+{discovery-goal}
+
+**Key Themes:**
+{key-themes-summary}
+
+**Top Opportunity Areas:**
+{top-3-opportunities}
+
+**Confidence Level:** {overall-confidence}
+
+---
+
+## Discovery Scope
+
+**Goal:** {discovery-goal-detailed}
+
+**Research Questions:**
+{research-questions-list}
+
+**User Population:**
+{user-population-description}
+
+**Success Criteria:**
+{success-criteria}
+
+---
+
+## Research Methods Used
+
+| Method | Participants / Sources | Duration | Key Focus |
+|--------|----------------------|----------|-----------|
+{methods-table}
+
+**Total research effort:** {total-sessions} sessions across {total-methods} methods over {total-duration}
+
+---
+
+## Key Themes
+
+### Theme 1: {theme-1-name}
+
+**Pattern:** {theme-1-pattern}
+
+**Evidence:**
+{theme-1-evidence}
+
+**Implication:** {theme-1-implication}
+
+**Representative Quote:**
+> "{theme-1-quote}" -- {theme-1-source}
+
+---
+
+### Theme 2: {theme-2-name}
+
+**Pattern:** {theme-2-pattern}
+
+**Evidence:**
+{theme-2-evidence}
+
+**Implication:** {theme-2-implication}
+
+**Representative Quote:**
+> "{theme-2-quote}" -- {theme-2-source}
+
+---
+
+### Theme 3: {theme-3-name}
+
+**Pattern:** {theme-3-pattern}
+
+**Evidence:**
+{theme-3-evidence}
+
+**Implication:** {theme-3-implication}
+
+**Representative Quote:**
+> "{theme-3-quote}" -- {theme-3-source}
+
+---
+
+{additional-themes}
+
+## Opportunity Areas
+
+**Priority:** High = Strong evidence + High impact | Medium = Moderate evidence or impact | Low = Emerging signal
+
+### Opportunity 1: {opportunity-1-name}
+
+- **User Evidence:** {opportunity-1-evidence}
+- **Size Signal:** {opportunity-1-size}
+- **Current Alternatives:** {opportunity-1-alternatives}
+- **Strategic Fit:** {opportunity-1-fit}
+- **Priority:** {opportunity-1-priority}
+
+### Opportunity 2: {opportunity-2-name}
+
+- **User Evidence:** {opportunity-2-evidence}
+- **Size Signal:** {opportunity-2-size}
+- **Current Alternatives:** {opportunity-2-alternatives}
+- **Strategic Fit:** {opportunity-2-fit}
+- **Priority:** {opportunity-2-priority}
+
+### Opportunity 3: {opportunity-3-name}
+
+- **User Evidence:** {opportunity-3-evidence}
+- **Size Signal:** {opportunity-3-size}
+- **Current Alternatives:** {opportunity-3-alternatives}
+- **Strategic Fit:** {opportunity-3-fit}
+- **Priority:** {opportunity-3-priority}
+
+{additional-opportunities}
+
+---
+
+## Research Question Answers
+
+### Q1: {research-question-1}
+
+**Answer:** {answer-1}
+
+**Confidence:** {confidence-1}
+
+**Key Evidence:** {evidence-1}
+
+---
+
+### Q2: {research-question-2}
+
+**Answer:** {answer-2}
+
+**Confidence:** {confidence-2}
+
+**Key Evidence:** {evidence-2}
+
+---
+
+### Q3: {research-question-3}
+
+**Answer:** {answer-3}
+
+**Confidence:** {confidence-3}
+
+**Key Evidence:** {evidence-3}
+
+---
+
+{additional-question-answers}
+
+## Evidence Matrix
+
+| Theme / Pattern | {participant-columns} | Survey | Analytics | Total Sources |
+|----------------|----------------------|--------|-----------|---------------|
+{evidence-matrix-rows}
+
+---
+
+## Contradictions and Outliers
+
+{contradictions-and-outliers}
+
+---
+
+## Limitations
+
+**Sample limitations:**
+{sample-limitations}
+
+**Method limitations:**
+{method-limitations}
+
+**Scope limitations:**
+{scope-limitations}
+
+---
+
+## Recommended Next Steps
+
+1. {next-step-1}
+2. {next-step-2}
+3. {next-step-3}
+4. {next-step-4}
+5. {next-step-5}
+
+---
+
+## Follow-Up Research Needed
+
+{follow-up-research}
+
+---
+
+## Research Sources
+
+{research-sources-detailed}
+
+---
+
+## Validation Checklist
+
+- [ ] All research questions addressed with evidence
+- [ ] Themes supported by multiple methods (triangulation)
+- [ ] Opportunity areas include size signals and priority
+- [ ] Contradictions and limitations documented honestly
+- [ ] Report reviewed by at least one team member not involved in research
+- [ ] Stakeholders briefed on key findings
+- [ ] Next steps assigned with owners and timelines
+
+---
+
+**Created by:** {creator-name}
+**Created with:** Isla (discovery-empathy-expert) - Convoke v2.0.0
+**Date:** {creation-date}
+**Version:** 1.0
+**Status:** {status}
+
+---
+
+*This discovery report is a living document. Update it as new research emerges or as the team acts on the findings.*

package/_bmad/bme/_vortex/workflows/user-discovery/validate.md

@@ -0,0 +1,153 @@
+---
+workflow: validate-user-discovery
+type: single-file
+description: Validate a user discovery report for research rigor, method appropriateness, and finding quality
+author: Isla (discovery-empathy-expert)
+---
+
+# Validate User Discovery Report
+
+Bring me a user discovery report and I'll help you assess its research rigor, method appropriateness, and the quality of its findings.
+
+## Why Validation Matters
+
+Discovery research shapes product strategy. If the research is flawed -- biased samples, weak methods, unsupported conclusions -- the strategy built on it will be flawed too. Validation catches these problems before they compound into costly product decisions.
+
+## Validation Process
+
+### 1. Research Rigor Check
+
+**Is the discovery scope well-defined?**
+- Clear goal tied to a business or product decision?
+- Research questions that are specific and answerable?
+- User population defined with inclusion and exclusion criteria?
+
+**Is the evidence base sufficient?**
+- Multiple participants (not just 1-2 anecdotes)?
+- Multiple methods used (triangulation)?
+- Evidence cited for every claim?
+
+**Red Flags:**
+- "We believe users want..." (belief is not evidence)
+- "Based on our experience..." (team experience is not user research)
+- Findings from a single session presented as patterns
+- No participant count or sample description
+- Conclusions that go far beyond what the data supports
+
+### 2. Method Appropriateness Check
+
+**Were the right methods used for the right questions?**
+
+| Question Type | Strong Methods | Weak Methods |
+|--------------|----------------|--------------|
+| Understanding workflows | Contextual inquiry, observation | Surveys |
+| Measuring prevalence | Surveys, analytics | Interviews alone |
+| Discovering motivations | Contextual inquiry, diary studies | Analytics alone |
+| Tracking behavior over time | Diary studies, analytics | Single-session interviews |
+| Uncovering environment factors | Observation, contextual inquiry | Remote surveys |
+
+**Red Flags:**
+- Using surveys to "discover" needs (surveys confirm, they don't discover)
+- Drawing motivational conclusions from analytics alone
+- Relying entirely on self-reported data without behavioral observation
+- Using a single method for all research questions
+
+### 3. Finding Quality Check
+
+**Are themes evidence-based?**
+- Each theme supported by data from multiple participants?
+- Each theme supported by more than one method?
+- Representative quotes that ring true (not cherry-picked)?
+- Frequency counts provided (not just "some users")?
+
+**Are opportunity areas grounded?**
+- Size signal provided (how many users, how often, how severe)?
+- Current alternatives documented (what do users do today)?
+- Priority justified by evidence, not gut feeling?
+
+**Red Flags:**
+- Themes that are really just topic labels ("Onboarding" vs. "Users skip onboarding and return later when stuck")
+- Opportunity areas with no size signal
+- Priorities that don't match the evidence strength
+- Missing contradictions section (all research has contradictions -- if none are reported, they were probably ignored)
+
+### 4. Bias and Limitations Check
+
+**Sample bias:**
+- Were only happy customers studied? (survivorship bias)
+- Were participants recruited from a single channel? (selection bias)
+- Were certain segments underrepresented?
+- Is the sample size adequate for the claims being made?
+
+**Researcher bias:**
+- Is there evidence of confirmation bias (only findings that match the hypothesis)?
+- Were leading questions used in interviews or surveys?
+- Did the same person conduct research AND synthesize findings? (perspective blindness)
+- Are interpretations separated from observations?
+
+**Honest limitations:**
+- Does the report acknowledge what was NOT learned?
+- Are confidence levels realistic?
+- Are follow-up research recommendations specific?
+
+### 5. Actionability Check
+
+**Can this report drive decisions?**
+- Can a product manager use the opportunity areas to prioritize a roadmap?
+- Can a designer use the themes to inform personas or journey maps?
+- Can a stakeholder understand the key findings in under 5 minutes?
+- Are next steps specific with clear owners?
+
+**Red Flags:**
+- Findings are interesting but not actionable ("Users are complex" -- so what?)
+- No clear connection between themes and opportunity areas
+- Next steps are vague ("Do more research")
+- Report reads like an academic paper instead of a decision tool
+
+---
+
+## Your Turn
+
+**Please share:**
+1. The user discovery report you want to validate (paste content or provide file path)
+2. The original research questions that motivated the discovery
+3. Any context about how the research was conducted
+
+I'll review it and provide:
+- **Rigor assessment** - Is the evidence base trustworthy?
+- **Method critique** - Were the right methods used for the right questions?
+- **Finding quality** - Are themes and opportunities well-supported?
+- **Bias check** - What blind spots might exist?
+- **Actionability score** - Can this report drive real decisions?
+- **Validation score** - Overall assessment
+
+---
+
+## Validation Criteria
+
+**Strong Discovery Report:**
+- Every theme supported by evidence from 2+ methods
+- Opportunity areas include size signals, alternatives, and priority
+- Limitations documented honestly
+- Sample described with inclusion/exclusion criteria
+- Contradictions and outliers discussed
+- Actionable for product, design, and strategy teams
+
+**Needs Work:**
+- Some themes lack multi-method support
+- Opportunity areas missing size signals or priority justification
+- Limitations mentioned but not detailed
+- Sample described but potential biases not discussed
+- Next steps are generic
+
+**Weak:**
+- Findings based on single method or tiny sample
+- No triangulation between methods
+- Claims exceed the evidence
+- No limitations section
+- Reads as opinions dressed in research language
+- Not actionable
+
+---
+
+Ready to validate your discovery report? Share it with me and I'll provide a thorough assessment.

package/_bmad/bme/_vortex/workflows/user-discovery/workflow.md

@@ -0,0 +1,45 @@
+---
+workflow: user-discovery
+type: step-file
+description: Plan and execute user discovery research to understand users, contexts, and needs
+author: Isla (discovery-empathy-expert)
+version: 1.5.0
+---
+
+# User Discovery Research Workflow
+
+This workflow guides you through planning and executing broader discovery research to understand your users, their contexts, and their unmet needs. Unlike a single empathy map session, user discovery spans multiple research methods and produces a comprehensive synthesis of what you learn.
+
+## What is User Discovery?
+
+User discovery is the practice of systematically learning about the people you aim to serve before committing to solutions. It goes beyond interviews to include contextual inquiry, observation, diary studies, surveys, and analytics review. The goal is to build deep, evidence-based understanding of user behaviors, motivations, and environments so that every product decision is grounded in reality.
+
+## Workflow Structure
+
+**Step-file architecture:**
+- Just-in-time loading (each step loads only when needed)
+- Sequential enforcement (must complete step N before step N+1)
+- State tracking in frontmatter (progress preserved)
+
+## Steps Overview
+
+1. **Define Discovery Scope** - What do we need to learn and why? Formulate research questions.
+2. **Choose Research Methods** - Select appropriate methods (contextual inquiry, diary studies, ethnographic observation, surveys, analytics review).
+3. **Plan Research Activities** - Timeline, participants, logistics, and ethical considerations.
+4. **Execute Research** - Guidance for conducting fieldwork (observation techniques, note-taking, staying open).
+5. **Organize Raw Data** - Affinity mapping, tagging, and categorization of research data.
+6. **Synthesize Discovery Findings** - Distill key themes, insights, and opportunity areas into an actionable artifact.
+
+## Output
+
+**Artifact:** User discovery report in `{output_folder}/user-discovery-{topic}-{date}.md`
+
+**Template:** Uses [user-discovery.template.md](user-discovery.template.md)
+
+---
+
+## INITIALIZATION
+
+Load config from {project-root}/_bmad/bme/_vortex/config.yaml
+
+Load step: {project-root}/_bmad/bme/_vortex/workflows/user-discovery/steps/step-01-discovery-scope.md

package/_bmad/bme/_vortex/workflows/user-interview/steps/step-01-research-goals.md

@@ -0,0 +1,100 @@
+---
+step: 1
+workflow: user-interview
+title: Define Research Goals
+---
+
+# Step 1: Define Research Goals
+
+Before writing a single interview question, you need clarity on what you want to learn and why it matters to your product decisions.
+
+## Why This Matters
+
+Research without clear goals produces interesting stories but no actionable insights. Well-defined goals help you:
+- Stay focused during interviews instead of wandering
+- Know when you've learned enough to act
+- Prioritize which questions matter most
+- Connect findings directly to product decisions
+- Avoid "research theater" -- doing interviews to feel productive without learning anything useful
+
+## Your Task
+
+Answer these questions to define your research goals:
+
+### 1. What is the primary research question?
+
+State the single most important thing you need to learn. Be specific.
+
+**Weak:** "What do users think about our product?"
+**Strong:** "Why do users who sign up for a free trial abandon it within the first 3 days?"
+
+**Weak:** "How do people manage their finances?"
+**Strong:** "What triggers freelancers to look for invoicing software, and what do they try before finding a paid tool?"
+
+### 2. What decisions will this research inform?
+
+Research must connect to decisions. Otherwise it sits in a document no one reads.
+
+Examples:
+- "Should we invest in onboarding improvements or new features?"
+- "Which of our three persona hypotheses is closest to reality?"
+- "Is this problem painful enough that users would pay to solve it?"
+
+### 3. What do you already know (or believe)?
+
+List your existing assumptions. Be honest about what is validated versus what is a guess.
+
+**Format:**
+- VALIDATED: {insight} -- Source: {how you know this}
+- ASSUMPTION: {belief} -- Confidence: High/Medium/Low
+- UNKNOWN: {question you cannot answer today}
+
+### 4. What would change your mind?
+
+Define what a surprising or contradictory finding would look like. This prevents confirmation bias.
+
+Example: "If fewer than 2 out of 8 participants mention onboarding as a pain point, we should deprioritize the onboarding redesign."
+
+### 5. How many interviews do you plan to conduct?
+
+General guidance:
+- **5-8 interviews** for exploratory discovery (finding new problems)
+- **8-12 interviews** for validating a specific hypothesis
+- **3-5 interviews** for usability or task-based feedback
+- You will typically see patterns emerge after 5-6 interviews on the same topic
+
+## Example
+
+**Primary Research Question:**
+Why do small business owners (1-10 employees) continue using spreadsheets for project tracking even after evaluating dedicated project management tools?
+
+**Decisions This Informs:**
+- Whether to position our tool as a "spreadsheet replacement" or a "spreadsheet complement"
+- Which 3 features to prioritize in Q2 to reduce switching friction
+- Whether our pricing is a barrier or if the issue is something else entirely
+
+**What We Know:**
+- VALIDATED: 62% of trial users import data from spreadsheets -- Source: onboarding analytics
+- ASSUMPTION: Users find PM tools "too complex" for small teams -- Confidence: Medium
+- ASSUMPTION: Price is a secondary concern; learning curve is primary -- Confidence: Low
+- UNKNOWN: What specific spreadsheet workflows are they reluctant to give up?
+
+**What Would Change Our Mind:**
+- If most participants say price is the primary blocker, we need to rethink our freemium strategy
+- If participants are happy with spreadsheets and don't feel pain, this market may not be viable
+
+**Planned Interviews:** 8 (small business owners who evaluated but did not adopt a PM tool)
+
+---
+
+## Your Turn
+
+Please define your research goals using the structure above.
+
+**Tip:** If you cannot clearly state what decision this research will inform, you are not ready to interview. Spend more time on goal definition first.
+
+## Next Step
+
+When you've defined clear research goals, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/user-interview/steps/step-02-interview-script.md

package/_bmad/bme/_vortex/workflows/user-interview/steps/step-02-interview-script.md

@@ -0,0 +1,123 @@
+---
+step: 2
+workflow: user-interview
+title: Design Interview Script
+---
+
+# Step 2: Design Interview Script
+
+Now that you have clear research goals, let's design an interview script that draws out honest, detailed responses without leading participants toward the answers you want to hear.
+
+## Why This Matters
+
+The quality of your insights depends entirely on the quality of your questions. Leading questions produce false confidence. Closed questions produce shallow data. A well-designed script helps you:
+- Get authentic stories instead of socially desirable answers
+- Uncover behaviors (what people actually do) not just opinions (what people say they'd do)
+- Maintain consistency across interviews while leaving room for exploration
+- Avoid the most common interview pitfalls that waste everyone's time
+
+## Question Design Principles
+
+### The Five Rules of Interview Questions
+
+1. **Ask about the past, not the future.** "Tell me about the last time you..." beats "Would you ever...?" People are terrible at predicting their own behavior.
+
+2. **Ask open-ended questions.** Questions that can be answered with "yes" or "no" kill conversations. Start with "Tell me about...", "Walk me through...", "Describe...", "What happened when..."
+
+3. **Never lead the witness.** "Don't you think the onboarding is confusing?" will always get a "yes." Instead: "Walk me through your first experience with the product."
+
+4. **Follow emotion and energy.** When a participant's voice changes, they lean forward, or they hesitate -- that's where the real insight lives. Probe deeper there.
+
+5. **Separate behavior from opinion.** "Do you like using spreadsheets?" (opinion) vs. "How many hours last week did you spend in spreadsheets?" (behavior). Behavior is more reliable.
+
+### Common Bias Traps to Avoid
+
+| Bias Trap | Example (Bad) | Fix (Good) |
+|-----------|---------------|------------|
+| Leading question | "How frustrating is the checkout process?" | "Walk me through your last purchase." |
+| Hypothetical | "Would you use a feature that does X?" | "How do you handle X today?" |
+| Binary question | "Is the dashboard useful?" | "How do you use the dashboard in your daily work?" |
+| Stacking questions | "What do you think about the price and the features and the design?" | Ask one question at a time. |
+| Priming | "We built this feature to save time. How much time does it save you?" | "Tell me about your experience with this feature." |
+
+## Your Task
+
+Design your interview script using the structure below:
+
+### 1. Opening (2-3 minutes)
+
+Write a brief introduction that:
+- Thanks the participant for their time
+- Explains the purpose (in general terms, without biasing)
+- Sets expectations (duration, recording permission, no right/wrong answers)
+- Asks permission to take notes or record
+
+**Example opening:**
+> "Thank you for taking the time to talk with me today. I'm researching how [role/persona] handle [general topic]. There are no right or wrong answers -- I'm genuinely curious about your experience. This will take about 30-45 minutes. Is it okay if I take notes? Everything you share will be kept confidential."
+
+### 2. Warm-up Questions (3-5 minutes)
+
+Start with easy, non-threatening questions to build rapport and get context.
+
+**Examples:**
+- "Tell me about your role. What does a typical day look like?"
+- "How long have you been doing [activity/role]?"
+- "What tools or processes do you use most in your work?"
+
+### 3. Core Questions (20-30 minutes)
+
+These are your main research questions. Design 5-8 core questions tied directly to your research goals.
+
+**For each question, include:**
+- The main question
+- 2-3 follow-up probes if the answer is shallow
+- What you're trying to learn (internal note, not shared with participant)
+
+**Example format:**
+> **Q: "Walk me through the last time you [relevant activity]."**
+> - Probe: "What happened next?"
+> - Probe: "How did that make you feel?"
+> - Probe: "What did you try before that?"
+> - *Learning goal: Understand the real workflow and pain points*
+
+### 4. Closing Questions (5 minutes)
+
+Wrap up with reflective and forward-looking questions:
+- "Is there anything I should have asked but didn't?"
+- "What's the one thing you wish was different about [topic]?"
+- "Is there anyone else you think I should talk to about this?"
+
+### 5. Debrief Notes (post-interview, for interviewer only)
+
+After each interview, immediately capture:
+- Top 3 surprising things you heard
+- Quotes that stood out
+- Body language or emotional moments
+- What would you ask differently next time?
+
+## Script Quality Checklist
+
+Before finalizing, verify your script passes these checks:
+
+- [ ] Every core question is open-ended (cannot be answered yes/no)
+- [ ] No question contains the answer you're hoping to hear
+- [ ] Questions focus on past behavior, not future predictions
+- [ ] You ask about specific instances ("last time") not generalizations ("usually")
+- [ ] Questions progress from easy/broad to specific/deep
+- [ ] You have probes ready for shallow answers
+- [ ] The script can be completed in the planned time
+- [ ] You have not revealed your product idea or solution before asking about problems
+
+---
+
+## Your Turn
+
+Please design your interview script using the structure above. I'll review it for leading questions, bias, and alignment with your research goals.
+
+**Tip:** The best interviews feel like conversations, not interrogations. Your script is a guide, not a rigid questionnaire. Be prepared to deviate when the participant says something interesting.
+
+## Next Step
+
+When your interview script is ready, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/user-interview/steps/step-03-recruitment.md