bmad-enhanced 1.6.0 → 1.6.2

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

@@ -0,0 +1,213 @@
+# Isla User Guide - Discovery & Empathy Expert 🔍
+
+**Agent:** Isla (discovery-empathy-expert)
+**Version:** 1.5.0
+**Module:** BMAD Enhanced (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: Slash Command (Preferred)
+
+If you're in a BMAD environment that supports slash commands:
+
+```
+/bmad-agent-bme-discovery-empathy-expert
+```
+
+**If you see "Unknown skill":**
+This means slash commands aren't available in your environment. Use Method 2 instead.
+
+---
+
+### Method 2: Direct Agent File Reading (Always Works)
+
+In any environment (including Claude Code), you can invoke Isla by reading her agent file:
+
+1. Navigate to your BMAD project root
+2. Read the file: `_bmad/bme/_vortex/agents/discovery-empathy-expert.md`
+3. Isla will activate and greet you
+
+**Example (Claude Code):**
+```
+Read the file at _bmad/bme/_vortex/agents/discovery-empathy-expert.md
+```
+
+**Example (Terminal):**
+```bash
+cat _bmad/bme/_vortex/agents/discovery-empathy-expert.md
+```
+
+---
+
+## 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 bmad-install-vortex-agents`
+
+### Error: "Cannot load discovery workflow"
+
+**How to fix:**
+1. Check workflow files exist in `_bmad/bme/_vortex/workflows/`
+2. Run `npx bmad-doctor` to diagnose
+3. If missing: `npx bmad-install-vortex-agents`
+
+---
+
+## 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:** BMAD Enhanced (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! 🔍

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

@@ -0,0 +1,218 @@
+# Max User Guide - Learning & Decision Expert 🧭
+
+**Agent:** Max (learning-decision-expert)
+**Version:** 1.5.0
+**Module:** BMAD Enhanced (bme) - Vortex Pattern
+**Last Updated:** 2026-02-20
+
+---
+
+## Quick Start
+
+**Who is Max?**
+Max is a validated learning synthesizer and strategic decision expert. He helps teams turn experiment results into clear decisions using structured frameworks. He guides you through the "Systematize" stream of the Vortex pattern — capturing learnings, making pivot/patch/persevere decisions, and navigating between Vortex streams.
+
+**When to use Max:**
+- After running experiments (with Wade) — capture what you learned
+- When you need to decide: pivot, patch, or persevere
+- When you're unsure which Vortex stream to focus on next
+- When experiment data needs structured analysis
+- When the team needs to align on a strategic decision
+
+**What you'll get:**
+Learning cards, pivot/patch/persevere assessments, Vortex navigation recommendations — all evidence-based and decision-focused.
+
+---
+
+## How to Invoke Max
+
+### Method 1: Slash Command (Preferred)
+
+If you're in a BMAD environment that supports slash commands:
+
+```
+/bmad-agent-bme-learning-decision-expert
+```
+
+**If you see "Unknown skill":**
+Use Method 2 instead.
+
+---
+
+### Method 2: Direct Agent File Reading (Always Works)
+
+In any environment (including Claude Code), invoke Max by reading his agent file:
+
+1. Navigate to your BMAD project root
+2. Read the file: `_bmad/bme/_vortex/agents/learning-decision-expert.md`
+3. Max will activate and greet you
+
+**Example (Claude Code):**
+```
+Read the file at _bmad/bme/_vortex/agents/learning-decision-expert.md
+```
+
+**Example (Terminal):**
+```bash
+cat _bmad/bme/_vortex/agents/learning-decision-expert.md
+```
+
+---
+
+## Max's Menu Options
+
+Once Max activates, you'll see menu options for his available workflows:
+
+```
+1. [MH] Redisplay Menu Help
+2. [CH] Chat with Max about validated learning, decisions, and strategy
+3. [LC] Learning Card: Capture what was tested, learned, and decided
+4. [PP] Pivot/Patch/Persevere: Decision framework after experiments
+5. [VN] Vortex Navigation: Decide which stream to focus on next
+6. [VE] Validate: Review learning cards and decision 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 `LC` to create a learning card
+3. **Fuzzy Match:** Type `learning` or `pivot` - Max will match the command
+
+---
+
+## Workflows
+
+### [LC] Learning Card (6 steps)
+
+Capture validated learnings from experiments as structured learning cards.
+
+**Steps:**
+1. Experiment Context
+2. Raw Results
+3. Analysis
+4. Validated Learning
+5. Implications
+6. Synthesize
+
+**Output:** `{output_folder}/learning-card-{experiment-name}-{date}.md`
+**Time:** 30-45 minutes
+
+---
+
+### [PP] Pivot/Patch/Persevere (6 steps)
+
+Structured decision framework for deciding direction after experiments.
+
+**Steps:**
+1. Evidence Review
+2. Hypothesis Assessment
+3. Option Analysis (Pivot/Patch/Persevere)
+4. Stakeholder Input
+5. Decision
+6. Action Plan
+
+**Output:** `{output_folder}/pivot-patch-persevere-{topic}-{date}.md`
+**Time:** 45-90 minutes
+
+**The Three Options:**
+- **Pivot** - Change direction fundamentally (new hypothesis, new segment, new approach)
+- **Patch** - Adjust the current approach (tweak, iterate, refine)
+- **Persevere** - Stay the course (evidence supports the current direction)
+
+---
+
+### [VN] Vortex Navigation (6 steps)
+
+Decide which Vortex stream to focus on next based on current evidence and gaps.
+
+**Steps:**
+1. Current State Assessment
+2. Evidence Inventory
+3. Gap Analysis
+4. Stream Evaluation
+5. Recommendation
+6. Navigation Plan
+
+**Output:** `{output_folder}/vortex-navigation-{date}.md`
+**Time:** 30-60 minutes
+
+---
+
+## Max's Philosophy: Data Tells a Story
+
+### The Systematize Stream (Vortex Pattern)
+
+Max guides teams through the "Systematize" stream:
+- **Data tells a story — learn to read it** - Raw data is noise until you extract the signal
+- **Every experiment has a lesson, even failed ones** - Negative results are still validated learning
+- **Decide and move — analysis paralysis kills innovation** - Make the best decision with available evidence, then act
+- **Pivot is not failure, it's intelligence** - Changing direction based on evidence is a sign of strength
+- **Systematize what you learn** - Captured learning compounds; uncaptured learning evaporates
+
+---
+
+## Chatting with Max (CH)
+
+Select **[CH] Chat** to discuss:
+- Validated learning methodology
+- Experiment result interpretation
+- Strategic decision-making frameworks
+- Pivot vs. persevere decisions
+- Evidence-based product strategy
+- Vortex stream navigation
+
+**Example questions:**
+- "I ran several experiments and need to decide what to do next"
+- "How do I know if my experiment results are significant?"
+- "When should I pivot vs. persevere?"
+- "Which Vortex stream should I focus on?"
+- "How do I capture learnings so my team doesn't repeat mistakes?"
+
+---
+
+## Troubleshooting
+
+### Error: "Configuration Error: Cannot load config file"
+
+**How to fix:**
+1. Check if `_bmad/bme/_vortex/config.yaml` exists
+2. If missing: `npx bmad-install-vortex-agents`
+
+### Error: "Cannot load learning workflow"
+
+**How to fix:**
+1. Check workflow files exist in `_bmad/bme/_vortex/workflows/`
+2. Run `npx bmad-doctor` to diagnose
+3. If missing: `npx bmad-install-vortex-agents`
+
+---
+
+## Tips from Max
+
+### "Separate observation from interpretation"
+When capturing experiment results, first record what happened (raw data). Then, separately, analyze what it means. Mixing the two leads to confirmation bias.
+
+### "The evidence suggests..."
+Start every decision discussion with evidence, not opinion. If you can't point to data, you're guessing — and that's okay, as long as you know you're guessing.
+
+### "Three options, always"
+When facing a decision, always generate at least three options. The first two feel obvious. The third often reveals the real insight.
+
+### "Failed experiments are the most valuable"
+A "failed" experiment that clearly invalidates an assumption saves months of building the wrong thing. Celebrate the learning, not just the success.
+
+---
+
+## Credits
+
+**Agent:** Max (learning-decision-expert)
+**Module:** BMAD Enhanced (bme)
+**Submodule:** Vortex Pattern (_vortex)
+**Stream:** Systematize (Stream 7)
+**Version:** 1.5.0
+
+---
+
+**Questions?** Chat with Max (CH) - he's here to help you turn data into decisions! 🧭