convoke-agents 2.0.0

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

@@ -0,0 +1,250 @@
+---
+title: "User Interview Report: {topic}"
+date: {date}
+created-by: {user-name} with Isla (discovery-empathy-expert)
+type: user-interview
+status: DRAFT
+version: 1.0
+---
+
+# User Interview Report: {topic}
+
+> **Status:** DRAFT -- Review findings and insights before sharing broadly. Insights are based on qualitative evidence and should be validated further before major investment decisions.
+
+## Executive Summary
+
+**Research Question:**
+{primary-research-question}
+
+**Interviews Conducted:** {count} participants over {timeframe}
+
+**Top Insights:**
+1. {insight-1-summary}
+2. {insight-2-summary}
+3. {insight-3-summary}
+
+**Recommended Next Steps:**
+{next-steps-summary}
+
+---
+
+## Research Goals
+
+### Primary Research Question
+{primary-research-question}
+
+### Decisions This Research Informs
+{decisions}
+
+### Prior Assumptions
+{prior-assumptions}
+
+### What Would Change Our Mind
+{change-criteria}
+
+---
+
+## Interview Script
+
+### Opening
+{opening-script}
+
+### Warm-up Questions
+{warmup-questions}
+
+### Core Questions
+{core-questions-with-probes}
+
+### Closing Questions
+{closing-questions}
+
+### Script Revisions Made During Research
+{script-revisions}
+
+---
+
+## Participants
+
+| ID | Date | Duration | Context | Channel |
+|----|------|----------|---------|---------|
+| P1 | {date} | {min} min | {context} | {channel} |
+| P2 | {date} | {min} min | {context} | {channel} |
+| P3 | {date} | {min} min | {context} | {channel} |
+
+**Screening Criteria Used:**
+{screening-criteria}
+
+**Recruitment Channels:**
+{recruitment-channels}
+
+---
+
+## Raw Findings
+
+### Interview P1
+
+**Key Behaviors:**
+{p1-behaviors}
+
+**Notable Quotes:**
+{p1-quotes}
+
+**Pain Points:**
+{p1-pain-points}
+
+**Workarounds:**
+{p1-workarounds}
+
+**Emotional Moments:**
+{p1-emotions}
+
+**Assumptions Affected:**
+{p1-assumptions}
+
+---
+
+### Interview P2
+
+**Key Behaviors:**
+{p2-behaviors}
+
+**Notable Quotes:**
+{p2-quotes}
+
+**Pain Points:**
+{p2-pain-points}
+
+**Workarounds:**
+{p2-workarounds}
+
+**Emotional Moments:**
+{p2-emotions}
+
+**Assumptions Affected:**
+{p2-assumptions}
+
+---
+
+*(Repeat for each participant)*
+
+---
+
+## Synthesized Insights
+
+### Theme 1: {theme-1-name}
+
+**Insight:** {insight-statement}
+
+**Strength:** {Strong / Moderate / Emerging}
+**Based on:** {N} of {total} participants
+
+**Evidence:**
+{evidence-list}
+
+**Counter-evidence:**
+{counter-evidence}
+
+**Confidence:** {High / Medium / Low}
+
+**Implication:** {what-this-means-for-product}
+
+---
+
+### Theme 2: {theme-2-name}
+
+**Insight:** {insight-statement}
+
+**Strength:** {Strong / Moderate / Emerging}
+**Based on:** {N} of {total} participants
+
+**Evidence:**
+{evidence-list}
+
+**Counter-evidence:**
+{counter-evidence}
+
+**Confidence:** {High / Medium / Low}
+
+**Implication:** {what-this-means-for-product}
+
+---
+
+### Theme 3: {theme-3-name}
+
+**Insight:** {insight-statement}
+
+**Strength:** {Strong / Moderate / Emerging}
+**Based on:** {N} of {total} participants
+
+**Evidence:**
+{evidence-list}
+
+**Counter-evidence:**
+{counter-evidence}
+
+**Confidence:** {High / Medium / Low}
+
+**Implication:** {what-this-means-for-product}
+
+---
+
+## Recommendations
+
+### Immediate Actions
+{immediate-actions}
+
+### Further Research Needed
+{further-research}
+
+### Assumptions Validated
+{validated-assumptions}
+
+### Assumptions Invalidated
+{invalidated-assumptions}
+
+### New Questions to Investigate
+{new-questions}
+
+---
+
+## Research Quality Assessment
+
+### Sample Quality
+{sample-quality-assessment}
+
+### Question Quality
+{question-quality-assessment}
+
+### Confidence Assessment
+{confidence-assessment}
+
+### What We Would Do Differently
+{improvements-for-next-round}
+
+---
+
+## Saturation Tracker
+
+| Interview | New Findings | Repeated Findings | New Themes |
+|-----------|-------------|-------------------|------------|
+| P1 | {n} | {n} | {n} |
+| P2 | {n} | {n} | {n} |
+| P3 | {n} | {n} | {n} |
+
+---
+
+## Next Steps
+
+1. {next-step-1}
+2. {next-step-2}
+3. {next-step-3}
+
+**Suggested follow-up workflows:**
+- Emma's lean-persona workflow to build personas from these insights
+- Wade's lean-experiment workflow to validate riskiest assumptions
+
+---
+
+**Created with:** Convoke v2.0.0 - Vortex Pattern (Empathize Stream)
+**Agent:** Isla (Discovery & Empathy Expert)
+**Workflow:** user-interview

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

@@ -0,0 +1,142 @@
+---
+validation: user-interview
+type: single-file
+description: Validate user interview artifacts for evidence quality, question bias, and finding specificity
+author: Isla (discovery-empathy-expert)
+version: 1.5.0
+---
+
+# Validate User Interview Report
+
+**Agent:** Isla (Discovery & Empathy Expert)
+
+**Stream:** Empathize
+
+## Overview
+
+This validation checks that a user interview report meets quality standards for evidence-based research. It ensures insights are grounded in real data, questions avoid bias, and findings are specific enough to act on.
+
+## Validation Checks
+
+### 1. Evidence Quality
+
+**What it checks:** Are insights backed by sufficient, specific evidence from actual interviews?
+
+**Pass criteria:**
+- Every insight references at least 2 participant IDs with specific quotes or behaviors
+- Evidence includes direct quotes (in quotation marks), not paraphrases
+- Counter-evidence is acknowledged where it exists (not hidden)
+- Confidence levels are stated and justified
+- Saturation is tracked (new findings vs. repeated findings per interview)
+
+**Common failures:**
+- Insights with no attributed evidence ("users want X" without saying which users)
+- All evidence comes from a single participant (one person's opinion presented as a pattern)
+- Only confirming evidence is cited; contradictions are ignored
+- Quotes are paraphrased instead of verbatim, introducing interviewer bias
+
+### 2. Question Bias Check
+
+**What it checks:** Does the interview script avoid leading, hypothetical, and binary questions?
+
+**Pass criteria:**
+- No core question can be answered with "yes" or "no"
+- No question contains value-laden language ("frustrating", "difficult", "amazing")
+- No question reveals the desired answer ("Don't you think X would be better?")
+- Questions ask about past behavior, not hypothetical future behavior
+- No question presupposes a problem ("How frustrated are you with..." assumes frustration)
+- Probing questions are included for each core question
+
+**Common failures:**
+- "Would you use a feature that does X?" (hypothetical -- untestable)
+- "How painful is your current process?" (presupposes pain and leads with "painful")
+- "Do you like the dashboard?" (binary -- produces yes/no)
+- "We're building X to solve Y. What do you think?" (reveals solution before exploring problem)
+
+### 3. Finding Specificity
+
+**What it checks:** Are findings concrete and actionable, or vague and generic?
+
+**Pass criteria:**
+- Findings include specific numbers, frequencies, or timeframes when available
+- Pain points describe observable behaviors, not just feelings
+- Workarounds are described with enough detail to understand the actual workflow
+- Each finding is attributed to a specific participant (P1, P2, etc.)
+- Findings distinguish between what participants said vs. what they did
+
+**Common failures:**
+- "Users are frustrated" (vague -- which users? about what specifically? how do you know?)
+- "Most participants mentioned they'd want feature X" (unspecific -- how many? in response to what question? did they mention it unprompted or in response to a leading question?)
+- "The process is slow" (unmeasured -- how slow? compared to what? according to whom?)
+
+### 4. Research Rigor
+
+**What it checks:** Does the overall research process meet minimum quality standards?
+
+**Pass criteria:**
+- Research goals are clearly stated and connected to specific decisions
+- At least 5 participants were interviewed (minimum for pattern identification)
+- Participant screening criteria are documented
+- Contradictions between participants are captured and explored
+- Research quality self-assessment is honest (acknowledges limitations)
+- Script revisions during the research process are documented
+- Assumptions from before the research are explicitly compared against findings
+
+**Common failures:**
+- Research goals are missing or vague ("understand users better")
+- Fewer than 5 interviews with claims of "all users want X"
+- No screening criteria documented (unclear who was interviewed and why)
+- All findings conveniently align with the team's existing beliefs (confirmation bias)
+- No acknowledgment of limitations or areas of uncertainty
+
+### 5. Actionability
+
+**What it checks:** Do the insights lead to concrete, specific next steps?
+
+**Pass criteria:**
+- Each insight has a stated implication for the product
+- Recommendations are specific enough to act on (not "improve onboarding" but "show value within first 3 minutes by auto-importing existing data")
+- There is a clear distinction between "act on now" and "investigate further"
+- New questions generated by the research are captured for future investigation
+- Recommended next steps include which Vortex workflows to use (e.g., lean-persona, lean-experiment)
+
+**Common failures:**
+- Insights without implications ("users do X" -- so what?)
+- Generic recommendations ("we should talk to more users")
+- No prioritization (everything is equally important, which means nothing is)
+- No connection to follow-up research or experimentation
+
+## Validation Scoring
+
+| Check | Weight | Score |
+|-------|--------|-------|
+| Evidence Quality | 30% | {pass/partial/fail} |
+| Question Bias | 20% | {pass/partial/fail} |
+| Finding Specificity | 20% | {pass/partial/fail} |
+| Research Rigor | 15% | {pass/partial/fail} |
+| Actionability | 15% | {pass/partial/fail} |
+
+**Overall:** {PASS / NEEDS REVISION / FAIL}
+
+## Remediation Guidance
+
+**If Evidence Quality fails:**
+Go back to raw notes and recordings. Add specific participant IDs, direct quotes, and behavioral observations. Acknowledge counter-evidence you may have glossed over.
+
+**If Question Bias fails:**
+Revise the interview script using the bias checklist in Step 2. If interviews are already done, note the bias in your research quality assessment and caveat affected insights.
+
+**If Finding Specificity fails:**
+Return to Step 5 and add concrete details: numbers, frequencies, specific tools named, exact workflows described. Replace vague language with observable behaviors.
+
+**If Research Rigor fails:**
+If the issue is sample size, conduct additional interviews before synthesizing. If the issue is missing documentation, go back and fill in screening criteria, research goals, and limitations.
+
+**If Actionability fails:**
+For each insight, ask: "If a product manager read this, what would they do on Monday morning?" If you can't answer that, the insight needs to be sharpened or connected to a specific decision.
+
+---
+
+**Created with:** Convoke v2.0.0 - Vortex Pattern (Empathize Stream)
+**Agent:** Isla (Discovery & Empathy Expert)
+**Workflow:** user-interview

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

@@ -0,0 +1,51 @@
+---
+workflow: user-interview
+type: step-file
+description: Design interview scripts, conduct user interviews, and synthesize findings into actionable insights
+author: Isla (discovery-empathy-expert)
+version: 1.5.0
+---
+
+# User Interview Workflow
+
+This workflow guides you through the full lifecycle of user interviews, from defining research goals to synthesizing insights that drive product decisions.
+
+## What is a User Interview?
+
+A user interview is a qualitative research method where you have a structured conversation with a real or potential user to understand their experiences, needs, and behaviors. Unlike surveys, interviews let you go deep:
+
+- **Uncover the "why"** - Understand motivations and reasoning behind behaviors
+- **Discover unknowns** - Surface problems and needs you didn't know existed
+- **Build empathy** - Develop genuine understanding of your users' world
+- **Generate hypotheses** - Create testable assumptions grounded in real stories
+- **Validate or invalidate** - Test existing assumptions against lived experience
+
+## 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 Research Goals** - What do you need to learn and why?
+2. **Design Interview Script** - Craft open-ended questions that avoid bias
+3. **Plan Participant Recruitment** - Identify and recruit the right participants
+4. **Conduct Interviews** - Guidance for active listening, probing, and note-taking
+5. **Capture Findings** - Document raw findings from each interview session
+6. **Synthesize Insights** - Identify patterns, themes, and actionable insights
+
+## Output
+
+**Artifact:** User interview report in `{output_folder}/user-interview-{topic}-{date}.md`
+
+**Template:** Uses [user-interview.template.md](user-interview.template.md)
+
+---
+
+## INITIALIZATION
+
+Load config from {project-root}/_bmad/bme/_vortex/config.yaml
+
+Load step: {project-root}/_bmad/bme/_vortex/workflows/user-interview/steps/step-01-research-goals.md

package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-01-current-state.md

@@ -0,0 +1,56 @@
+---
+step: 1
+workflow: vortex-navigation
+title: Current State Assessment
+---
+
+# Step 1: Current State Assessment
+
+Before deciding where to go next, we need to understand where you are now. Let's map your progress across the Vortex streams.
+
+## Your Task
+
+For each of the 7 Vortex streams, assess your current status:
+
+### Stream Status Map
+
+| # | Stream | Status | Key Artifacts | Confidence |
+|---|--------|--------|---------------|------------|
+| 1 | **Contextualize** | {not-started / in-progress / complete} | {list artifacts} | {low / medium / high} |
+| 2 | **Empathize** | {status} | {artifacts} | {confidence} |
+| 3 | **Synthesize** | {status} | {artifacts} | {confidence} |
+| 4 | **Hypothesize** | {status} | {artifacts} | {confidence} |
+| 5 | **Externalize** | {status} | {artifacts} | {confidence} |
+| 6 | **Sensitize** | {status} | {artifacts} | {confidence} |
+| 7 | **Systematize** | {status} | {artifacts} | {confidence} |
+
+### Status Definitions
+
+- **Not started** - No work done in this stream
+- **In progress** - Some work done but not complete
+- **Complete** - Core activities finished, artifacts produced
+
+### Confidence Levels
+
+- **Low** - Based on assumptions or limited evidence
+- **Medium** - Some evidence supports the work, but gaps remain
+- **High** - Strong evidence base, validated through research or experiments
+
+### Context Questions
+
+1. How long has your team been working on this product/problem?
+2. What triggered the need to navigate streams right now?
+3. Are there external deadlines or constraints affecting your priorities?
+4. What is the team's biggest uncertainty right now?
+
+---
+
+## Your Turn
+
+Please fill in the stream status map and answer the context questions. Be honest about confidence levels -- overestimating progress leads to poor navigation decisions.
+
+## Next Step
+
+When you've completed the assessment, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-02-evidence-inventory.md

package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-02-evidence-inventory.md

@@ -0,0 +1,70 @@
+---
+step: 2
+workflow: vortex-navigation
+title: Evidence Inventory
+---
+
+# Step 2: Evidence Inventory
+
+Now let's take stock of all the evidence you've accumulated. Decisions are only as good as the evidence behind them.
+
+## Your Task
+
+### Artifact Inventory
+
+List all artifacts produced so far, organized by stream:
+
+**Contextualize artifacts:**
+- [ ] Product vision document
+- [ ] Lean personas
+- [ ] Problem space definition
+- [ ] Other: {list}
+
+**Empathize artifacts:**
+- [ ] Empathy maps
+- [ ] User interview findings
+- [ ] Discovery research synthesis
+- [ ] Other: {list}
+
+**Externalize artifacts:**
+- [ ] Experiment results / learning cards
+- [ ] MVP test results
+- [ ] Proof of concept findings
+- [ ] Proof of value findings
+- [ ] Other: {list}
+
+**Systematize artifacts:**
+- [ ] Learning cards
+- [ ] Pivot/patch/persevere decisions
+- [ ] Previous navigation recommendations
+- [ ] Other: {list}
+
+### Evidence Quality Assessment
+
+For each piece of evidence, rate its quality:
+
+| Artifact | Source | Age | Sample Size | Quality |
+|----------|--------|-----|-------------|---------|
+| {name} | {research/experiment/assumption} | {days/weeks} | {n=?} | {strong/moderate/weak} |
+
+### Key Learnings Summary
+
+What are the top 5 things you've learned so far?
+
+1. {learning 1} — Evidence: {source}
+2. {learning 2} — Evidence: {source}
+3. {learning 3} — Evidence: {source}
+4. {learning 4} — Evidence: {source}
+5. {learning 5} — Evidence: {source}
+
+---
+
+## Your Turn
+
+Complete the artifact inventory and evidence quality assessment. Don't count assumptions as evidence -- only include things backed by research, experiments, or data.
+
+## Next Step
+
+When your evidence inventory is complete, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-03-gap-analysis.md

package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-03-gap-analysis.md

@@ -0,0 +1,76 @@
+---
+step: 3
+workflow: vortex-navigation
+title: Gap Analysis
+---
+
+# Step 3: Gap Analysis
+
+Now let's identify what's missing. Gaps in your knowledge are the strongest signal for where to navigate next.
+
+## Your Task
+
+### Untested Assumptions
+
+List your critical assumptions that remain untested:
+
+| Assumption | Risk if Wrong | Stream to Test | Priority |
+|------------|--------------|----------------|----------|
+| {assumption} | {impact: high/medium/low} | {which stream} | {1-5} |
+
+### Knowledge Gaps by Stream
+
+**Contextualize gaps:**
+- Do you know who your target user is? (Specific, not generic)
+- Do you understand the problem space clearly?
+- Is your product vision validated or assumed?
+
+**Empathize gaps:**
+- Have you talked to real users? How many?
+- Do you understand their emotional experience?
+- Are your personas based on research or imagination?
+
+**Synthesize gaps:**
+- Have you combined insights from multiple sources?
+- Do patterns emerge from your research?
+- Are there contradictions you haven't resolved?
+
+**Hypothesize gaps:**
+- Do you have testable hypotheses?
+- Are they specific and falsifiable?
+- Have you prioritized which to test first?
+
+**Externalize gaps:**
+- Have you tested your riskiest assumptions?
+- Do experiment results support or challenge your direction?
+- Is your evidence statistically meaningful?
+
+**Sensitize gaps:**
+- Have you measured user reaction to prototypes?
+- Do you have feedback loops in place?
+- Are you tracking the right metrics?
+
+**Systematize gaps:**
+- Have you captured learnings from experiments?
+- Have you made explicit decisions based on evidence?
+- Is there a clear decision trail?
+
+### Critical Gap Identification
+
+Which single gap, if filled, would most reduce your risk?
+
+**Critical gap:** {description}
+**Why critical:** {rationale}
+**Stream to address it:** {stream name}
+
+---
+
+## Your Turn
+
+Complete the gap analysis. Focus on gaps that represent real risk -- not just "nice to know" but "need to know before we can move forward."
+
+## Next Step
+
+When the gap analysis is complete, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-04-stream-evaluation.md

package/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-04-stream-evaluation.md

@@ -0,0 +1,57 @@
+---
+step: 4
+workflow: vortex-navigation
+title: Stream Evaluation
+---
+
+# Step 4: Stream Evaluation
+
+With your current state, evidence, and gaps mapped, let's evaluate which streams are the best candidates for your next focus.
+
+## Your Task
+
+### Evaluation Criteria
+
+Rate each candidate stream on these dimensions (1-5 scale):
+
+| Criterion | Description |
+|-----------|-------------|
+| **Gap severity** | How critical is the knowledge gap this stream would fill? |
+| **Risk reduction** | How much would this stream reduce your biggest uncertainties? |
+| **Dependency** | Does other work depend on completing this stream first? |
+| **Feasibility** | Can you realistically execute this stream right now? (resources, skills, access) |
+| **Time sensitivity** | Is there urgency? Will the opportunity to learn disappear? |
+
+### Stream Scoring Matrix
+
+| Stream | Gap Severity | Risk Reduction | Dependency | Feasibility | Time Sensitivity | **Total** |
+|--------|-------------|----------------|------------|-------------|-----------------|-----------|
+| Contextualize | {1-5} | {1-5} | {1-5} | {1-5} | {1-5} | {sum} |
+| Empathize | {1-5} | {1-5} | {1-5} | {1-5} | {1-5} | {sum} |
+| Synthesize | {1-5} | {1-5} | {1-5} | {1-5} | {1-5} | {sum} |
+| Hypothesize | {1-5} | {1-5} | {1-5} | {1-5} | {1-5} | {sum} |
+| Externalize | {1-5} | {1-5} | {1-5} | {1-5} | {1-5} | {sum} |
+| Sensitize | {1-5} | {1-5} | {1-5} | {1-5} | {1-5} | {sum} |
+| Systematize | {1-5} | {1-5} | {1-5} | {1-5} | {1-5} | {sum} |
+
+### Anti-Patterns to Watch For
+
+Before finalizing scores, check for these navigation anti-patterns:
+
+- **Comfort zone bias** - Choosing familiar streams over ones where you have the biggest gaps
+- **Analysis paralysis** - Cycling through Contextualize/Empathize without ever Externalizing
+- **Premature optimization** - Jumping to Sensitize before validating core hypotheses
+- **Skipping Empathize** - Building for imagined users instead of real ones
+- **Ignoring Systematize** - Running experiments without capturing learnings
+
+---
+
+## Your Turn
+
+Complete the scoring matrix. Be honest about feasibility -- a high-priority stream you can't execute is less useful than a medium-priority stream you can start tomorrow.
+
+## Next Step
+
+When the evaluation is complete, I'll load:
+
+{project-root}/_bmad/bme/_vortex/workflows/vortex-navigation/steps/step-05-recommendation.md