convoke-agents 2.0.0

package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-04-execute.md

@@ -0,0 +1,169 @@
+---
+step: 4
+workflow: user-discovery
+title: Execute Research
+---
+
+# Step 4: Execute Research
+
+Your plan is set. Now it's time to go into the field and learn. This step provides guidance for conducting rigorous, respectful research that produces trustworthy data.
+
+## Why This Matters
+
+The quality of your discovery findings depends entirely on the quality of your data collection. Sloppy notes, leading questions, or confirmation bias during execution will undermine everything that follows. Good fieldwork requires discipline, humility, and genuine curiosity.
+
+## Guidance by Method
+
+### Conducting Contextual Inquiry
+
+**Before the session:**
+- Review your discussion guide but do not memorize it -- you need flexibility
+- Arrive early and observe the environment before engaging
+- Test your recording equipment
+
+**During the session:**
+- Start with rapport building (5 minutes of casual conversation)
+- Ask the participant to walk you through their normal process
+- Use the "master-apprentice" model: "Teach me how you do this"
+- Follow their lead -- if they go off-script, follow the thread
+- Ask "why" and "tell me more" rather than closed questions
+- Note the environment: what's on their desk, screen, walls?
+- Capture exact quotes when something feels important
+
+**Key phrases to use:**
+- "Can you show me how you'd normally do that?"
+- "What were you thinking just now when you paused?"
+- "Is that what usually happens, or was that unusual?"
+- "You mentioned [X] -- can you tell me more about that?"
+- "What would happen if you didn't do that step?"
+
+**Key phrases to avoid:**
+- "Would you like it if the product did [X]?" (leading)
+- "Don't you think [X] would be better?" (leading)
+- "Most people we've talked to say [X]..." (anchoring)
+- "That's interesting!" (can steer the conversation)
+
+**After the session:**
+- Write up expanded notes within 2 hours while memory is fresh
+- Highlight surprising moments, contradictions, and strong emotions
+- Note your own reactions and biases ("I assumed X but saw Y")
+
+### Running Diary Studies
+
+**Launch phase:**
+- Brief each participant individually (not just via email)
+- Walk them through one example entry so they understand the format
+- Set expectations: "This should take about 5 minutes per entry"
+- Confirm their preferred reminder channel (text, email, app notification)
+
+**During the study:**
+- Send daily reminders at consistent times
+- Respond to entries within 24 hours with brief acknowledgments
+- Ask clarifying follow-up questions on entries that seem rich
+- Monitor completion rates -- reach out personally to participants who stop logging
+- Do NOT judge or evaluate entries ("There are no wrong answers")
+
+**Managing quality:**
+- If entries are too brief, ask: "Can you tell me a bit more about what happened right before/after?"
+- If entries are too long, gently remind: "Focus on the moment that felt most significant"
+- If entries become repetitive, introduce a prompt variation: "Today, focus specifically on moments of frustration"
+
+### Conducting Ethnographic Observation
+
+**Positioning:**
+- Find a vantage point where you can see without being in the way
+- Avoid hovering directly behind someone's screen
+- If observing a shared space, position yourself as a natural part of the environment
+
+**What to record:**
+- Timestamp every observation
+- Describe actions objectively: "User clicked back button 3 times" not "User was confused"
+- Note the sequence of actions, especially unexpected detours
+- Record environmental factors: interruptions, conversations with colleagues, phone checks
+- Sketch the physical layout if relevant
+
+**Staying objective:**
+- Separate observations from interpretations in your notes
+- Use two columns: "I saw/heard" and "I think this means"
+- Resist the urge to interpret in the moment -- just capture
+- After the session, review your interpretation column critically
+
+**The debrief:**
+- After observing, sit with the participant for 15-20 minutes
+- Ask them to explain key moments you observed
+- Share what surprised you and ask if your interpretation matches their experience
+- This is where the richest insights often emerge
+
+### Administering Surveys
+
+**Before launch:**
+- Pilot with 3-5 people and watch them complete it (time them, note confusion)
+- Revise any question where someone hesitates or asks "what do you mean?"
+- Check that response options are mutually exclusive and collectively exhaustive
+- Test on mobile -- many respondents will use their phone
+
+**During collection:**
+- Monitor response rates daily
+- Send one reminder after 3 days, a final reminder at 1 day before close
+- Watch for suspicious patterns (all same answers, impossibly fast completion)
+- If open-ended responses are thin, consider a follow-up prompt
+
+**Quality checks:**
+- Remove responses completed in under 30% of median time
+- Flag straight-line responses (same answer for every question)
+- Check for contradictory answers that suggest inattention
+
+### Conducting Analytics Review
+
+**Approach:**
+- Start with the user journey map and overlay behavioral data at each stage
+- Look for drop-offs, loops, and unexpected paths
+- Compare segments: do different user groups behave differently?
+- Check for temporal patterns: time of day, day of week, seasonality
+
+**What to capture:**
+- Key metrics with context (not just numbers, but what they mean)
+- Anomalies that warrant qualitative investigation
+- Hypotheses generated from the data (to test with other methods)
+- Confidence level for each finding (strong signal vs. noisy data)
+
+## Universal Field Notes Best Practices
+
+### The AEIOU Framework
+
+Use this structure for every observation session:
+
+- **A - Activities:** What are people doing? What tasks and steps are involved?
+- **E - Environments:** What is the physical or digital space like? What objects and tools are present?
+- **I - Interactions:** How do people interact with each other, with tools, with the environment?
+- **O - Objects:** What artifacts, devices, and items do people use or create?
+- **U - Users:** Who are the people involved? What are their roles, relationships, and emotional states?
+
+### Staying Open
+
+The hardest part of discovery research is staying open to being wrong. Watch for these traps:
+
+- **Confirmation bias:** Noticing evidence that supports your hypothesis and ignoring evidence that contradicts it
+- **Premature synthesis:** Jumping to conclusions after 2 sessions instead of waiting for patterns
+- **Solution fixation:** Hearing problems and immediately designing solutions in your head
+- **Expert blindness:** Assuming you understand the user's perspective because you've been in the domain a long time
+
+**Antidote:** After each session, write down one thing that surprised you. If nothing surprised you, you probably were not listening carefully enough.
+
+---
+
+## Your Turn
+
+As you execute your research, come back and share:
+1. Key observations and quotes from your sessions
+2. Anything that surprised you or contradicted your assumptions
+3. Emerging patterns you're noticing across sessions
+4. Any adjustments you need to make to your plan
+
+I'll help you make sense of what you're finding and suggest adjustments to remaining sessions based on what emerges.
+
+## Next Step
+
+When your research execution is complete (or you have enough data to synthesize), I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/user-discovery/steps/step-05-organize-data.md

package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-05-organize-data.md

@@ -0,0 +1,149 @@
+---
+step: 5
+workflow: user-discovery
+title: Organize Raw Data
+---
+
+# Step 5: Organize Raw Data
+
+You've collected research data across multiple sessions and methods. Before you can synthesize insights, you need to organize this raw material into a structure that makes patterns visible.
+
+## Why This Matters
+
+Raw research data -- scattered notes, recordings, survey exports, analytics screenshots -- is overwhelming and unusable in its unprocessed form. Organization is the bridge between "we did research" and "we know something." Teams that skip this step end up with anecdotes instead of insights, and recency bias instead of patterns.
+
+## Your Task
+
+### 1. Consolidate All Data Sources
+
+Gather everything into one accessible location:
+
+- Expanded field notes from contextual inquiry sessions
+- Diary study entries (exported and compiled)
+- Observation field notes and environment sketches
+- Survey responses (raw export + summary statistics)
+- Analytics findings (screenshots, charts, key metrics)
+- Audio/video recordings (timestamped for reference)
+- Photos and artifacts collected during fieldwork
+
+**Naming convention:** `[method]-[participant/source]-[date]`
+- Example: `contextual-P03-2026-02-15.md`
+- Example: `diary-entries-compiled-2026-02-20.md`
+- Example: `analytics-onboarding-funnel-2026-02-18.md`
+
+### 2. Extract Atomic Observations
+
+Go through each data source and pull out individual observations. Each observation should be:
+
+- **Atomic:** One idea, one behavior, one quote per item
+- **Evidence-based:** Tied to a specific source (participant code, session date, data point)
+- **Descriptive:** What happened, not what you think it means (interpretation comes later)
+
+**Format each observation as:**
+```
+[Source: P03, contextual inquiry, 2026-02-15]
+User keeps a separate spreadsheet to track which emails she's sent because
+the CRM doesn't show sent-email status on the contact list view.
+```
+
+```
+[Source: Survey Q7, n=142]
+68% of respondents report checking their dashboard "several times a day"
+but only 12% take action based on what they see.
+```
+
+```
+[Source: Analytics, Jan 2026]
+Average session duration for the reporting feature is 47 seconds.
+Users who export reports spend 8 minutes. Most users view but don't act.
+```
+
+**Tip:** Aim for 100-300 atomic observations for a thorough discovery. This sounds like a lot, but 8 contextual inquiry sessions alone typically produce 150+.
+
+### 3. Affinity Mapping
+
+Affinity mapping is the core technique for finding patterns in qualitative data. Here is how to do it rigorously:
+
+**Step A: Spread out all observations**
+- If physical: write each observation on a sticky note or index card
+- If digital: use a tool like Miro, FigJam, or a simple spreadsheet
+
+**Step B: Group silently (if working with a team)**
+- Each person moves observations into clusters based on similarity
+- No talking during initial grouping -- this prevents one voice dominating
+- It's okay to move someone else's placement (disagreement is data)
+- Aim for 10-20 clusters initially
+
+**Step C: Name the clusters**
+- Once grouping stabilizes, give each cluster a descriptive name
+- The name should describe the PATTERN, not just the topic
+- Bad: "Onboarding" (topic label)
+- Good: "Users skip onboarding steps and return later when stuck" (pattern)
+- Good: "Workarounds reveal gaps in core workflow" (insight-oriented)
+
+**Step D: Identify super-clusters**
+- Look for clusters that relate to each other
+- Group related clusters into 3-7 themes
+- These themes become the backbone of your synthesis
+
+### 4. Tagging System
+
+Apply consistent tags to every observation for cross-cutting analysis:
+
+**Recommended tag categories:**
+
+| Category | Example Tags |
+|----------|-------------|
+| Method | `contextual`, `diary`, `observation`, `survey`, `analytics` |
+| Participant segment | `power-user`, `new-user`, `churned`, `enterprise`, `smb` |
+| Topic | `onboarding`, `collaboration`, `reporting`, `mobile` |
+| Sentiment | `frustration`, `delight`, `confusion`, `confidence` |
+| Behavior type | `workaround`, `habit`, `avoidance`, `exploration` |
+| Evidence strength | `observed`, `self-reported`, `quantified`, `inferred` |
+
+**Why tags matter:** They let you ask questions like "Show me all frustration moments from enterprise users during onboarding" -- slicing the data in ways that affinity clusters alone cannot.
+
+### 5. Quantify Where Possible
+
+Even in qualitative research, counting matters. It helps you distinguish between "one person said this" and "this came up in every single session."
+
+**Track frequency:**
+- How many participants mentioned or exhibited each pattern?
+- How many data sources support each theme?
+- What is the distribution of survey responses for key questions?
+
+**Use a simple evidence matrix:**
+
+| Theme / Pattern | P01 | P02 | P03 | P04 | P05 | Survey | Analytics | Count |
+|----------------|-----|-----|-----|-----|-----|--------|-----------|-------|
+| Workaround spreadsheets | X | | X | X | X | 34% | - | 4+survey |
+| Skip onboarding | X | X | X | | X | 61% | 72% bounce | 4+both |
+| Mobile frustration | | X | | X | | 28% | 45% mobile | 2+both |
+
+### 6. Note Contradictions and Outliers
+
+Do NOT discard data that doesn't fit the emerging patterns. Contradictions and outliers are often the most valuable findings.
+
+**Record:**
+- Observations that contradict a strong pattern (might reveal a segment difference)
+- Participants who behaved very differently from others (might be early adopters or edge cases)
+- Survey responses that conflict with qualitative findings (might indicate social desirability bias)
+- Analytics data that contradicts self-reports (what people do vs. what they say)
+
+---
+
+## Your Turn
+
+Please share:
+1. What data sources you have collected (list them)
+2. Your initial affinity clusters (even rough groupings are useful)
+3. Any patterns that are already emerging
+4. Any contradictions or surprises in the data
+
+I'll help you refine your organization and prepare for synthesis.
+
+## Next Step
+
+When your data is organized and initial patterns are identified, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/user-discovery/steps/step-06-synthesize.md

package/_bmad/bme/_vortex/workflows/user-discovery/steps/step-06-synthesize.md

@@ -0,0 +1,159 @@
+---
+step: 6
+workflow: user-discovery
+title: Synthesize Discovery Findings
+---
+
+# Step 6: Synthesize Discovery Findings
+
+This is where everything comes together. You'll distill your organized data into a clear, actionable discovery report that answers your research questions and reveals opportunity areas for your product.
+
+## Why This Matters
+
+Data without synthesis is just noise. Your stakeholders don't need 200 sticky notes -- they need 5 key themes, 3 opportunity areas, and a clear recommendation for what to do next. Synthesis is the intellectual work that transforms research into strategy.
+
+## Your Task
+
+### 1. Answer Your Research Questions
+
+Go back to the research questions you defined in Step 1. For each one:
+
+**State the answer clearly:**
+- One paragraph summary of what you learned
+- Confidence level: High (multiple sources, consistent pattern), Medium (some evidence, needs more validation), Low (limited data, emerging signal)
+- Key evidence supporting the answer (cite specific sources)
+
+**Example:**
+> **Question:** "What does a typical day look like for a small-business owner managing finances?"
+>
+> **Answer:** Small-business owners manage finances in fragmented bursts, not dedicated sessions. Across 6 contextual inquiry sessions, we observed that financial tasks (invoicing, expense tracking, bank reconciliation) are interleaved with core business activities and rarely receive more than 10 minutes of focused attention. Owners rely on 3-5 different tools and maintain at least one "backup" spreadsheet. The primary trigger for financial tasks is anxiety (upcoming tax deadline, low account balance alert), not routine.
+>
+> **Confidence:** High -- consistent across all participants and supported by diary study entries showing average 4.2 financial micro-sessions per day.
+
+### 2. Identify Key Themes (3-7)
+
+Themes are the big patterns that cut across multiple research questions and data sources. A good theme is:
+
+- Supported by evidence from multiple participants AND multiple methods
+- Descriptive of a pattern, not just a topic
+- Relevant to product decisions
+
+**Theme format:**
+
+**Theme: [Descriptive name]**
+- **Pattern:** What you observed happening consistently
+- **Evidence:** Sources and frequency (e.g., "6 of 8 participants, 68% of survey respondents, confirmed by analytics")
+- **Implication:** What this means for your product or strategy
+- **Quote:** One representative quote that brings the theme to life
+
+**Example:**
+> **Theme: Anxiety-driven financial management**
+> - **Pattern:** Financial tasks are triggered by fear of consequences (missed deadlines, cash flow problems) rather than proactive planning. Users react rather than plan.
+> - **Evidence:** Observed in 6/8 contextual sessions. Diary entries show 73% of financial tasks triggered by notifications or deadlines. Survey: 61% agree "I only look at my finances when something forces me to."
+> - **Implication:** Our product should reduce anxiety by providing early, gentle alerts rather than assuming users will proactively check dashboards.
+> - **Quote:** "I know I should look at this stuff more often, but honestly I only open it when I'm scared." -- P04
+
+### 3. Map Opportunity Areas
+
+Opportunity areas bridge research findings and product strategy. They answer: "Given what we learned, where should we invest?"
+
+**For each opportunity area:**
+
+- **Opportunity:** A clear statement of the unmet need or underserved job
+- **User evidence:** What you saw or heard that reveals this opportunity
+- **Size signal:** How many users are affected? How frequently? How severely?
+- **Current alternatives:** How do users solve this today? (Workarounds, competitors, manual processes)
+- **Strategic fit:** How does this align with your product vision and business goals?
+- **Priority:** High / Medium / Low based on evidence strength, user impact, and strategic fit
+
+**Example:**
+> **Opportunity: Proactive cash flow forecasting**
+> - **User evidence:** 7/8 participants expressed anxiety about cash flow surprises. 5 maintain manual spreadsheets to predict upcoming expenses.
+> - **Size signal:** 61% of survey respondents (n=142) report cash flow uncertainty as their #1 financial stress.
+> - **Current alternatives:** Manual spreadsheets (43%), gut feel (31%), accountant calls (15%), competitor tool (11%)
+> - **Strategic fit:** Aligns with our mission to "remove financial anxiety from running a business."
+> - **Priority:** High
+
+### 4. Document What You Did NOT Learn
+
+Intellectual honesty is a hallmark of rigorous research. State clearly:
+
+- Which research questions remain partially answered
+- What populations or contexts you did not study
+- What biases may exist in your sample
+- What follow-up research you recommend
+
+This builds credibility and helps future researchers avoid duplicating work or inheriting your blind spots.
+
+### 5. Create the Discovery Report
+
+I'll use the template at `user-discovery.template.md` to generate your final artifact.
+
+**Output File:** `{output_folder}/user-discovery-{topic}-{date}.md`
+
+### 6. Validation Questions
+
+Before we finalize, let's validate the synthesis:
+
+**Evidence rigor:**
+- [ ] Every theme is supported by evidence from at least 2 methods
+- [ ] Every opportunity area cites specific participant data or metrics
+- [ ] Confidence levels are honestly assessed
+- [ ] Contradictions and limitations are documented
+
+**Actionability:**
+- [ ] A product manager could use this to prioritize the next quarter's roadmap
+- [ ] A designer could use the themes to inform persona updates or journey maps
+- [ ] Stakeholders can understand the key findings in under 5 minutes
+- [ ] The report answers the original discovery goal from Step 1
+
+**Completeness:**
+- [ ] All research questions are addressed (even if partially)
+- [ ] Key themes cover the breadth of what was discovered
+- [ ] Opportunity areas include size signals and priority
+- [ ] Limitations and next steps are documented
+
+---
+
+## Your Turn
+
+Please provide:
+1. Your answers to each research question (with confidence levels)
+2. Your 3-7 key themes with evidence
+3. Your opportunity areas ranked by priority
+4. What you did NOT learn and what follow-up research you'd recommend
+
+I'll review your synthesis and help refine it into the final discovery report.
+
+## Output
+
+Once you confirm, I'll create:
+
+**File:** `{output_folder}/user-discovery-{topic}-{date}.md`
+
+**Contents:**
+- Executive Summary
+- Discovery Scope (goal, questions, population)
+- Research Methods Used
+- Key Themes (with evidence)
+- Opportunity Areas (prioritized)
+- Research Question Answers
+- Limitations and Next Steps
+- Research Sources
+
+---
+
+## Vortex Compass
+
+Based on what you just completed, here are your evidence-driven options:
+
+| If you learned... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Discovery findings ready for convergence | research-convergence | Mila 🔬 | Converge discovery findings into problem definition (HC1) |
+| Ready to test hypotheses | lean-experiment | Wade 🧪 | Design experiments from discovery insights |
+| Need deeper empathy for key users | empathy-map | Isla 🔍 | Map the users you discovered in depth |
+
+> **Note:** These are evidence-based recommendations. You can navigate to any Vortex agent
+> at any time based on your judgment.
+
+**Or run Max's [VN] Vortex Navigation** for a full gap analysis across all streams.