bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.10

package/src/modules/bmm/workflows/1-analysis/research/instructions-market.md

@@ -1,41 +1,62 @@
 # Market Research Workflow Instructions
 
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
+<critical>The workflow execution engine is governed by: {project_root}/{bmad_folder}/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>This is an INTERACTIVE workflow with web research capabilities. Engage the user at key decision points.</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
+<critical>This is a HIGHLY INTERACTIVE workflow - collaborate with user throughout, don't just gather info and disappear</critical>
+<critical>Web research is MANDATORY - use WebSearch tool with {{current_year}} for all market intelligence gathering</critical>
+<critical>Communicate all responses in {communication_language} and tailor to {user_skill_level}</critical>
+<critical>Generate all documents in {document_output_language}</critical>
+
+<critical>🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨</critical>
+<critical>NEVER invent market data - if you cannot find reliable data, explicitly state: "I could not find verified data for [X]"</critical>
+<critical>EVERY statistic, market size, growth rate, or competitive claim MUST have a cited source with URL</critical>
+<critical>For CRITICAL claims (TAM/SAM/SOM, market size, growth rates), require 2+ independent sources that agree</critical>
+<critical>When data sources conflict (e.g., different market size estimates), present ALL estimates with sources and explain variance</critical>
+<critical>Mark data confidence: [Verified - 2+ sources], [Single source - verify], [Estimated - low confidence]</critical>
+<critical>Clearly label: FACT (sourced data), ANALYSIS (your interpretation), PROJECTION (forecast/speculation)</critical>
+<critical>After each WebSearch, extract and store source URLs - include them in the report</critical>
+<critical>If a claim seems suspicious or too convenient, STOP and cross-verify with additional searches</critical>
+<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
 
 <!-- IDE-INJECT-POINT: market-research-subagents -->
 
 <workflow>
 
-<step n="1" goal="Research Discovery and Scoping">
-<action>Welcome the user and explain the market research journey ahead</action>
+<step n="1" goal="Discover research needs and scope collaboratively">
 
-Ask the user these critical questions to shape the research:
+<action>Welcome {user_name} warmly. Position yourself as their collaborative research partner who will:
 
-1. **What is the product/service you're researching?**
-   - Name and brief description
-   - Current stage (idea, MVP, launched, scaling)
+- Gather live {{current_year}} market data
+- Share findings progressively throughout
+- Help make sense of what we discover together
 
-2. **What are your primary research objectives?**
-   - Market sizing and opportunity assessment?
-   - Competitive intelligence gathering?
-   - Customer segment validation?
-   - Go-to-market strategy development?
-   - Investment/fundraising support?
-   - Product-market fit validation?
+Ask what they're building and what market questions they need answered.
+</action>
 
-3. **Research depth preference:**
-   - Quick scan (2-3 hours) - High-level insights
-   - Standard analysis (4-6 hours) - Comprehensive coverage
-   - Deep dive (8+ hours) - Exhaustive research with modeling
+<action>Through natural conversation, discover:
 
-4. **Do you have any existing research or documents to build upon?**
+- The product/service and current stage
+- Their burning questions (what they REALLY need to know)
+- Context and urgency (fundraising? launch decision? pivot?)
+- Existing knowledge vs. uncertainties
+- Desired depth (gauge from their needs, don't ask them to choose)
+
+Adapt your approach: If uncertain → help them think it through. If detailed → dig deeper.
+
+Collaboratively define scope:
+
+- Markets/segments to focus on
+- Geographic boundaries
+- Critical questions vs. nice-to-have
+  </action>
+
+<action>Reflect understanding back to confirm you're aligned on what matters.</action>
 
 <template-output>product_name</template-output>
 <template-output>product_description</template-output>
 <template-output>research_objectives</template-output>
-<template-output>research_depth</template-output>
+<template-output>research_scope</template-output>
 </step>
 
 <step n="2" goal="Market Definition and Boundaries">
@@ -65,49 +86,62 @@ Work with the user to establish:
 <template-output>segment_boundaries</template-output>
 </step>
 
-<step n="3" goal="Live Market Intelligence Gathering" if="enable_web_research == true">
-<action>Conduct real-time web research to gather current market data</action>
+<step n="3" goal="Gather live market intelligence collaboratively">
 
-<critical>This step performs ACTUAL web searches to gather live market intelligence</critical>
+<critical>This step REQUIRES WebSearch tool usage - gather CURRENT data from {{current_year}}</critical>
+<critical>Share findings as you go - make this collaborative, not a black box</critical>
 
-Conduct systematic research across multiple sources:
+<action>Let {user_name} know you're searching for current {{market_category}} market data: size, growth, analyst reports, recent trends. Tell them you'll share what you find in a few minutes and review it together.</action>
 
-<step n="3a" title="Industry Reports and Statistics">
-<action>Search for latest industry reports, market size data, and growth projections</action>
-Search queries to execute:
-- "[market_category] market size [geographic_scope] [current_year]"
-- "[market_category] industry report Gartner Forrester IDC McKinsey"
-- "[market_category] market growth rate CAGR forecast"
-- "[market_category] market trends [current_year]"
+<step n="3a" title="Search for market size and industry data">
+<action>Conduct systematic web searches using WebSearch tool:
 
-<elicit-required/>
-</step>
+<WebSearch>{{market_category}} market size {{geographic_scope}} {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} industry report Gartner Forrester IDC {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} market growth rate CAGR forecast {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} market trends {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} TAM SAM market opportunity {{current_year}}</WebSearch>
+</action>
+
+<action>Share findings WITH SOURCES including URLs and dates. Ask if it aligns with their expectations.</action>
+
+<action>CRITICAL - Validate data before proceeding:
 
-<step n="3b" title="Regulatory and Government Data">
-<action>Search government databases and regulatory sources</action>
-Search for:
-- Government statistics bureaus
-- Industry associations
-- Regulatory body reports
-- Census and economic data
+- Multiple sources with similar figures?
+- Recent sources ({{current_year}} or within 1-2 years)?
+- Credible sources (Gartner, Forrester, govt data, reputable pubs)?
+- Conflicts? Note explicitly, search for more sources, mark [Low Confidence]
+  </action>
+
+<action if="user_has_questions">Explore surprising data points together</action>
+
+<template-output>sources_market_size</template-output>
 </step>
 
-<step n="3c" title="News and Recent Developments">
-<action>Gather recent news, funding announcements, and market events</action>
-Search for articles from the last 6-12 months about:
-- Major deals and acquisitions
-- Funding rounds in the space
-- New market entrants
-- Regulatory changes
-- Technology disruptions
+<step n="3b" title="Search for recent news and developments" optional="true">
+<action>Search for recent market developments:
+
+<WebSearch>{{market_category}} news {{current_year}} funding acquisitions</WebSearch>
+<WebSearch>{{market_category}} recent developments {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} regulatory changes {{current_year}}</WebSearch>
+</action>
+
+<action>Share noteworthy findings:
+
+"I found some interesting recent developments:
+
+{{key_news_highlights}}
+
+Anything here surprise you or confirm what you suspected?"
+</action>
 </step>
 
-<step n="3d" title="Academic and Research Papers">
-<action>Search for academic research and white papers</action>
-Look for peer-reviewed studies on:
-- Market dynamics
-- Technology adoption patterns
-- Customer behavior research
+<step n="3c" title="Optional: Government and academic sources" optional="true">
+<action if="research needs high credibility">Search for authoritative sources:
+
+<WebSearch>{{market_category}} government statistics census data {{current_year}}</WebSearch>
+<WebSearch>{{market_category}} academic research white papers {{current_year}}</WebSearch>
+</action>
 </step>
 
 <template-output>market_intelligence_raw</template-output>
@@ -204,8 +238,7 @@ For each major segment, research and define:
 - Purchasing frequency
 - Budget allocation
 
-<elicit-required/>
-<template-output>segment_profile_{{segment_number}}</template-output>
+<template-output>segment*profile*{{segment_number}}</template-output>
 </step>
 
 <step n="5b" title="Jobs-to-be-Done Framework">
@@ -250,38 +283,35 @@ Analyze:
 </step>
 </step>
 
-<step n="6" goal="Competitive Intelligence" if="enable_competitor_analysis == true">
-<action>Conduct comprehensive competitive analysis</action>
+<step n="6" goal="Understand the competitive landscape">
+<action>Ask if they know their main competitors or if you should search for them.</action>
 
-<step n="6a" title="Competitor Identification">
-<action>Create comprehensive competitor list</action>
+<step n="6a" title="Discover competitors together">
+<action if="user doesn't know competitors">Search for competitors:
 
-Search for and categorize:
+<WebSearch>{{product_category}} competitors {{geographic_scope}} {{current_year}}</WebSearch>
+<WebSearch>{{product_category}} alternatives comparison {{current_year}}</WebSearch>
+<WebSearch>top {{product_category}} companies {{current_year}}</WebSearch>
+</action>
 
-1. **Direct Competitors** - Same solution, same market
-2. **Indirect Competitors** - Different solution, same problem
-3. **Potential Competitors** - Could enter market
-4. **Substitute Products** - Alternative approaches
-
-<ask>Do you have a specific list of competitors to analyze, or should I discover them through research?</ask>
+<action>Present findings. Ask them to pick the 3-5 that matter most (most concerned about or curious to understand).</action>
 </step>
 
-<step n="6b" title="Competitor Deep Dive" repeat="5">
-<action>For top 5 competitors, research and analyze</action>
+<step n="6b" title="Research each competitor together" repeat="for-each-selected-competitor">
+<action>For each competitor, search for:
+- Company overview, product features
+- Pricing model
+- Funding and recent news
+- Customer reviews and ratings
+
+Use {{current_year}} in all searches.
+</action>
 
-Gather intelligence on:
+<action>Share findings with sources. Ask what jumps out and if it matches expectations.</action>
 
-- Company overview and history
-- Product features and positioning
-- Pricing strategy and models
-- Target customer focus
-- Recent news and developments
-- Funding and financial health
-- Team and leadership
-- Customer reviews and sentiment
+<action if="user has follow-up questions">Dig deeper based on their interests</action>
 
-<elicit-required/>
-<template-output>competitor_analysis_{{competitor_number}}</template-output>
+<template-output>competitor-analysis-{{competitor_name}}</template-output>
 </step>
 
 <step n="6c" title="Competitive Positioning Map">
@@ -404,7 +434,6 @@ For each opportunity:
 - Risk assessment
 - Success criteria
 
-<elicit-required/>
 <template-output>market_opportunities</template-output>
 </step>
 
@@ -471,8 +500,8 @@ Provide mitigation strategies.
 
 <ask>Would you like to create a financial model with revenue projections based on the market analysis?</ask>
 
-<check>If yes:</check>
-Build 3-year projections:
+<check if="yes">
+  Build 3-year projections:
 
 - Revenue model based on SOM scenarios
 - Customer acquisition projections
@@ -481,64 +510,110 @@ Build 3-year projections:
 - Funding requirements
 
 <template-output>financial_projections</template-output>
+</check>
+
 </step>
 
-<step n="11" goal="Executive Summary Creation">
-<action>Synthesize all findings into executive summary</action>
+<step n="11" goal="Synthesize findings together into executive summary">
 
-<critical>Write this AFTER all other sections are complete</critical>
+<critical>This is the last major content section - make it collaborative</critical>
 
-Create compelling executive summary with:
+<action>Review the research journey together. Share high-level summaries of market size, competitive dynamics, customer insights. Ask what stands out most - what surprised them or confirmed their thinking.</action>
 
-**Market Opportunity:**
+<action>Collaboratively craft the narrative:
 
-- TAM/SAM/SOM summary
-- Growth trajectory
+- What's the headline? (The ONE thing someone should know)
+- What are the 3-5 critical insights?
+- Recommended path forward?
+- Key risks?
 
-**Key Insights:**
+This should read like a strategic brief, not a data dump.
+</action>
 
-- Top 3-5 findings
-- Surprising discoveries
-- Critical success factors
+<action>Draft executive summary and share. Ask if it captures the essence and if anything is missing or overemphasized.</action>
 
-**Competitive Landscape:**
+<template-output>executive_summary</template-output>
+</step>
 
-- Market structure
-- Positioning opportunity
+<step n="12" goal="Validate sources and compile report">
 
-**Strategic Recommendations:**
+<critical>MANDATORY SOURCE VALIDATION - Do NOT skip this step!</critical>
 
-- Priority actions
-- Go-to-market approach
-- Investment requirements
+<action>Before finalizing, conduct source audit:
 
-**Risk Summary:**
+Review every major claim in the report and verify:
 
-- Major risks
-- Mitigation approach
+**For Market Size Claims:**
 
-<template-output>executive_summary</template-output>
-</step>
+- [ ] At least 2 independent sources cited with URLs
+- [ ] Sources are from {{current_year}} or within 2 years
+- [ ] Sources are credible (Gartner, Forrester, govt data, reputable pubs)
+- [ ] Conflicting estimates are noted with all sources
+
+**For Competitive Data:**
+
+- [ ] Competitor information has source URLs
+- [ ] Pricing data is current and sourced
+- [ ] Funding data is verified with dates
+- [ ] Customer reviews/ratings have source links
 
-<step n="12" goal="Report Compilation and Review">
-<action>Compile full report and review with user</action>
+**For Growth Rates and Projections:**
 
-<action>Generate the complete market research report using the template</action>
-<action>Review all sections for completeness and consistency</action>
-<action>Ensure all data sources are properly cited</action>
+- [ ] CAGR and forecast data are sourced
+- [ ] Methodology is explained or linked
+- [ ] Multiple analyst estimates are compared if available
+
+**For Customer Insights:**
+
+- [ ] Persona data is based on real research (cited)
+- [ ] Survey/interview data has sample size and source
+- [ ] Behavioral claims are backed by studies/data
+      </action>
+
+<action>Count and document source quality:
+
+- Total sources cited: {{count_all_sources}}
+- High confidence (2+ sources): {{high_confidence_claims}}
+- Single source (needs verification): {{single_source_claims}}
+- Uncertain/speculative: {{low_confidence_claims}}
+
+If {{single_source_claims}} or {{low_confidence_claims}} is high, consider additional research.
+</action>
+
+<action>Compile full report with ALL sources properly referenced:
+
+Generate the complete market research report using the template:
+
+- Ensure every statistic has inline citation: [Source: Company, Year, URL]
+- Populate all {{sources_*}} template variables
+- Include confidence levels for major claims
+- Add References section with full source list
+  </action>
+
+<action>Present source quality summary to user:
+
+"I've completed the research with {{count_all_sources}} total sources:
+
+- {{high_confidence_claims}} claims verified with multiple sources
+- {{single_source_claims}} claims from single sources (marked for verification)
+- {{low_confidence_claims}} claims with low confidence or speculation
+
+Would you like me to strengthen any areas with additional research?"
+</action>
 
 <ask>Would you like to review any specific sections before finalizing? Are there any additional analyses you'd like to include?</ask>
 
 <goto step="9a" if="user requests changes">Return to refine opportunities</goto>
 
 <template-output>final_report_ready</template-output>
+<template-output>source_audit_complete</template-output>
 </step>
 
 <step n="13" goal="Appendices and Supporting Materials" optional="true">
 <ask>Would you like to include detailed appendices with calculations, full competitor profiles, or raw research data?</ask>
 
-<check>If yes:</check>
-Create appendices with:
+<check if="yes">
+  Create appendices with:
 
 - Detailed TAM/SAM/SOM calculations
 - Full competitor profiles
@@ -548,6 +623,53 @@ Create appendices with:
 - Glossary of terms
 
 <template-output>appendices</template-output>
+</check>
+
 </step>
 
+<step n="14" goal="Update status file on completion" tag="workflow-status">
+<check if="standalone_mode != true">
+  <action>Load the FULL file: {output_folder}/bmm-workflow-status.yaml</action>
+  <action>Find workflow_status key "research"</action>
+  <critical>ONLY write the file path as the status value - no other text, notes, or metadata</critical>
+  <action>Update workflow_status["research"] = "{output_folder}/bmm-research-{{research_mode}}-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<action>Find first non-completed workflow in workflow_status (next workflow to do)</action>
+<action>Determine next agent from path file based on next workflow</action>
+</check>
+
+<output>**✅ Research Complete ({{research_mode}} mode)**
+
+**Research Report:**
+
+- Research report generated and saved to {output_folder}/bmm-research-{{research_mode}}-{{date}}.md
+
+{{#if standalone_mode != true}}
+**Status Updated:**
+
+- Progress tracking updated: research marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
+
+**Next Steps:**
+
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
+- **Optional:** Review findings with stakeholders, or run additional analysis workflows (product-brief for software, or install BMGD module for game-brief)
+
+Check status anytime with: `workflow-status`
+{{else}}
+Since no workflow is in progress:
+
+- Review research findings
+- Refer to the BMM workflow guide if unsure what to do next
+- Or run `workflow-init` to create a workflow path and get guided next steps
+  {{/if}}
+  </output>
+  </step>
+
 </workflow>