bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.4

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

@@ -1,67 +1,129 @@
 # Market Research Report Validation Checklist
 
-## Research Foundation
+## 🚨 CRITICAL: Source Verification and Fact-Checking (PRIORITY)
 
-### Objectives and Scope
+### Source Citation Completeness
 
-- [ ] Research objectives are clearly stated with specific questions to answer
-- [ ] Market boundaries are explicitly defined (product category, geography, segments)
-- [ ] Research methodology is documented with data sources and timeframes
-- [ ] Limitations and assumptions are transparently acknowledged
+- [ ] **EVERY** market size claim has at least 2 cited sources with URLs
+- [ ] **EVERY** growth rate/CAGR has cited sources with URLs
+- [ ] **EVERY** competitive data point (pricing, features, funding) has sources with URLs
+- [ ] **EVERY** customer statistic or insight has cited sources
+- [ ] **EVERY** industry trend claim has sources from {{current_year}} or recent years
+- [ ] All sources include: Name, Date, URL (clickable links)
+- [ ] No claims exist without verifiable sources
 
-### Data Quality
+### Source Quality and Credibility
 
-- [ ] All data sources are cited with dates and links where applicable
-- [ ] Data is no more than 12 months old for time-sensitive metrics
-- [ ] At least 3 independent sources validate key market size claims
-- [ ] Source credibility is assessed (primary > industry reports > news articles)
-- [ ] Conflicting data points are acknowledged and reconciled
+- [ ] Market size sources are HIGH credibility (Gartner, Forrester, IDC, government data, industry associations)
+- [ ] NOT relying on single blog posts or unverified sources for critical data
+- [ ] Sources are recent ({{current_year}} or within 1-2 years for time-sensitive data)
+- [ ] Primary sources prioritized over secondary/tertiary sources
+- [ ] Paywalled reports are cited with proper attribution (e.g., "Gartner Market Report 2025")
 
-## Market Sizing Analysis
+### Multi-Source Verification (Critical Claims)
 
-### TAM Calculation
+- [ ] TAM calculation verified by at least 2 independent sources
+- [ ] SAM calculation methodology is transparent and sourced
+- [ ] SOM estimates are conservative and based on comparable benchmarks
+- [ ] Market growth rates corroborated by multiple analyst reports
+- [ ] Competitive market share data verified across sources
 
-- [ ] At least 2 different calculation methods are used (top-down, bottom-up, or value theory)
-- [ ] All assumptions are explicitly stated with rationale
-- [ ] Calculation methodology is shown step-by-step
-- [ ] Numbers are sanity-checked against industry benchmarks
-- [ ] Growth rate projections include supporting evidence
+### Conflicting Data Resolution
 
-### SAM and SOM
+- [ ] Where sources conflict, ALL conflicting estimates are presented
+- [ ] Variance between sources is explained (methodology, scope differences)
+- [ ] No arbitrary selection of "convenient" numbers without noting alternatives
+- [ ] Conflicting data is flagged with confidence levels
+- [ ] User is made aware of uncertainty in conflicting claims
 
-- [ ] SAM constraints are realistic and well-justified (geography, regulations, etc.)
-- [ ] SOM includes competitive analysis to support market share assumptions
-- [ ] Three scenarios (conservative, realistic, optimistic) are provided
-- [ ] Time horizons for market capture are specified (Year 1, 3, 5)
-- [ ] Market share percentages align with comparable company benchmarks
+### Confidence Level Marking
 
-## Customer Intelligence
+- [ ] Every major claim is marked with confidence level:
+  - **[Verified - 2+ sources]** = High confidence, multiple independent sources agree
+  - **[Single source - verify]** = Medium confidence, only one source found
+  - **[Estimated - low confidence]** = Low confidence, calculated/projected without strong sources
+- [ ] Low confidence claims are clearly flagged for user to verify independently
+- [ ] Speculative/projected data is labeled as PROJECTION or FORECAST, not presented as fact
 
-### Segment Analysis
+### Fact vs Analysis vs Speculation
 
-- [ ] At least 3 distinct customer segments are profiled
-- [ ] Each segment includes size estimates (number of customers or revenue)
-- [ ] Pain points are specific, not generic (e.g., "reduce invoice processing time by 50%" not "save time")
-- [ ] Willingness to pay is quantified with evidence
-- [ ] Buying process and decision criteria are documented
+- [ ] Clear distinction between:
+  - **FACT:** Sourced data with citations (e.g., "Market is $5.2B [Source: Gartner 2025]")
+  - **ANALYSIS:** Interpretation of facts (e.g., "This suggests strong growth momentum")
+  - **SPECULATION:** Educated guesses (e.g., "This trend may continue if...")
+- [ ] Analysis and speculation are NOT presented as verified facts
+- [ ] Recommendations are based on sourced facts, not unsupported assumptions
 
-### Jobs-to-be-Done
+### Anti-Hallucination Verification
 
-- [ ] Functional jobs describe specific tasks customers need to complete
-- [ ] Emotional jobs identify feelings and anxieties
-- [ ] Social jobs explain perception and status considerations
-- [ ] Jobs are validated with customer evidence, not assumptions
-- [ ] Priority ranking of jobs is provided
+- [ ] No invented statistics or "made up" market sizes
+- [ ] All percentages, dollar amounts, and growth rates are traceable to sources
+- [ ] If data couldn't be found, report explicitly states "No verified data available for [X]"
+- [ ] No use of vague sources like "industry experts say" without naming the expert/source
+- [ ] Version numbers, dates, and specific figures match source material exactly
 
-## Competitive Analysis
+## Market Sizing Analysis (Source-Verified)
 
-### Competitor Coverage
+### TAM Calculation Sources
 
-- [ ] At least 5 direct competitors are analyzed
-- [ ] Indirect competitors and substitutes are identified
-- [ ] Each competitor profile includes: company size, funding, target market, pricing
-- [ ] Recent developments (last 6 months) are included
-- [ ] Competitive advantages and weaknesses are specific, not generic
+- [ ] TAM figure has at least 2 independent source citations
+- [ ] Calculation methodology is sourced (not invented)
+- [ ] Industry benchmarks used for sanity-check are cited
+- [ ] Growth rate assumptions are backed by sourced projections
+- [ ] Any adjustments or filters applied are justified and documented
+
+### SAM and SOM Source Verification
+
+- [ ] SAM constraints are based on sourced data (addressable market scope)
+- [ ] SOM competitive assumptions cite actual competitor data
+- [ ] Market share benchmarks reference comparable companies with sources
+- [ ] Scenarios (conservative/realistic/optimistic) are justified with sourced reasoning
+
+## Competitive Analysis (Source-Verified)
+
+### Competitor Data Source Verification
+
+- [ ] **EVERY** competitor mentioned has source for basic company info
+- [ ] Competitor pricing data has sources (website URLs, pricing pages, reviews)
+- [ ] Funding amounts cite sources (Crunchbase, press releases, SEC filings)
+- [ ] Product features verified through sources (official website, documentation, reviews)
+- [ ] Market positioning claims are backed by sources (analyst reports, company statements)
+- [ ] Customer count/user numbers cite sources (company announcements, verified reports)
+- [ ] Recent news and developments cite article URLs with dates from {{current_year}}
+
+### Competitive Data Credibility
+
+- [ ] Company websites/official sources used for product info (highest credibility)
+- [ ] Financial data from Crunchbase, PitchBook, or SEC filings (not rumors)
+- [ ] Review sites cited for customer sentiment (G2, Capterra, TrustPilot with URLs)
+- [ ] Pricing verified from official pricing pages (with URL and date checked)
+- [ ] No assumptions about competitors without sourced evidence
+
+### Competitive Claims Verification
+
+- [ ] Market share claims cite analyst reports or verified data
+- [ ] "Leading" or "dominant" claims backed by sourced market data
+- [ ] Competitor weaknesses cited from reviews, articles, or public statements (not speculation)
+- [ ] Product comparison claims verified (feature lists from official sources)
+
+## Customer Intelligence (Source-Verified)
+
+### Customer Data Sources
+
+- [ ] Customer segment data cites research sources (reports, surveys, studies)
+- [ ] Demographics/firmographics backed by census data, industry reports, or studies
+- [ ] Pain points sourced from customer research, reviews, surveys (not assumed)
+- [ ] Willingness to pay backed by pricing studies, surveys, or comparable market data
+- [ ] Buying behavior sourced from research studies or industry data
+- [ ] Jobs-to-be-Done insights cite customer research or validated frameworks
+
+### Customer Insight Credibility
+
+- [ ] Primary research (if conducted) documents sample size and methodology
+- [ ] Secondary research cites the original study/report with full attribution
+- [ ] Customer quotes or testimonials cite the source (interview, review site, case study)
+- [ ] Persona data based on real research findings (not fictional archetypes)
+- [ ] No invented customer statistics or behaviors without source backing
 
 ### Positioning Analysis
 
@@ -115,23 +177,58 @@
 - [ ] Early warning indicators are defined
 - [ ] Contingency plans are outlined for high-impact risks
 
+## References and Source Documentation (CRITICAL)
+
+### References Section Completeness
+
+- [ ] Report includes comprehensive "References and Sources" section
+- [ ] Sources organized by category (market size, competitive, customer, trends)
+- [ ] Every source includes: Title/Name, Publisher, Date, Full URL
+- [ ] URLs are clickable and functional (not broken links)
+- [ ] Sources are numbered or organized for easy reference
+- [ ] Inline citations throughout report reference the sources section
+
+### Source Quality Metrics
+
+- [ ] Report documents total sources cited count
+- [ ] High confidence claims (2+ sources) count is reported
+- [ ] Single source claims are identified and counted
+- [ ] Low confidence/speculative claims are flagged
+- [ ] Web searches conducted count is included (for transparency)
+
+### Source Audit Trail
+
+- [ ] For each major section, sources are listed
+- [ ] TAM/SAM/SOM calculations show source for each number
+- [ ] Competitive data shows source for each competitor profile
+- [ ] Customer insights show research sources
+- [ ] Industry trends show article/report sources with dates
+
+### Citation Format Standards
+
+- [ ] Inline citations format: [Source: Company/Publication, Year, URL] or similar
+- [ ] Consistent citation style throughout document
+- [ ] No vague citations like "according to sources" without specifics
+- [ ] URLs are complete (not truncated)
+- [ ] Accessed/verified dates included for web sources
+
 ## Document Quality
 
-### Structure and Flow
+### Anti-Hallucination Final Check
 
-- [ ] Executive summary captures all key insights in 1-2 pages
-- [ ] Sections follow logical progression from market to strategy
-- [ ] No placeholder text remains (all {{variables}} are replaced)
-- [ ] Cross-references between sections are accurate
-- [ ] Table of contents matches actual sections
+- [ ] Read through entire report - does anything "feel" invented or too convenient?
+- [ ] Spot-check 5-10 random claims - can you find the cited source?
+- [ ] Check suspicious round numbers - are they actually from sources?
+- [ ] Verify any "shocking" statistics have strong sources
+- [ ] Cross-check key market size claims against multiple cited sources
 
-### Professional Standards
+### Structure and Completeness
 
-- [ ] Data visualizations effectively communicate insights
-- [ ] Technical terms are defined in glossary
-- [ ] Writing is concise and jargon-free
-- [ ] Formatting is consistent throughout
-- [ ] Document is ready for executive presentation
+- [ ] Executive summary captures all key insights
+- [ ] No placeholder text remains (all {{variables}} are replaced)
+- [ ] References section is complete and properly formatted
+- [ ] Source quality assessment included
+- [ ] Document ready for fact-checking by third party
 
 ## Research Completeness
 

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

@@ -2,50 +2,66 @@
 
 <critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.xml</critical>
 <critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
+<critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level}</critical>
 <critical>This workflow generates structured research prompts optimized for AI platforms</critical>
-<critical>Based on 2025 best practices from ChatGPT, Gemini, Grok, and Claude</critical>
+<critical>Based on {{current_year}} best practices from ChatGPT, Gemini, Grok, and Claude</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>🚨 BUILD ANTI-HALLUCINATION INTO PROMPTS 🚨</critical>
+<critical>Generated prompts MUST instruct AI to cite sources with URLs for all factual claims</critical>
+<critical>Include validation requirements: "Cross-reference claims with at least 2 independent sources"</critical>
+<critical>Add explicit instructions: "If you cannot find reliable data, state 'No verified data found for [X]'"</critical>
+<critical>Require confidence indicators in prompts: "Mark each claim with confidence level and source quality"</critical>
+<critical>Include fact-checking instructions: "Distinguish between verified facts, analysis, and speculation"</critical>
 
 <workflow>
 
-<step n="1" goal="Research Objective Discovery">
-<action>Understand what the user wants to research</action>
+<step n="1" goal="Discover what research prompt they need">
 
-**Let's create a powerful deep research prompt!**
+<action>Engage conversationally to understand their needs:
 
-<ask>What topic or question do you want to research?
+<check if="{user_skill_level} == 'expert'">
+  "Let's craft a research prompt optimized for AI deep research tools.
 
-Examples:
+What topic or question do you want to investigate, and which platform are you planning to use? (ChatGPT Deep Research, Gemini, Grok, Claude Projects)"
+</check>
 
-- "Future of electric vehicle battery technology"
-- "Impact of remote work on commercial real estate"
-- "Competitive landscape for AI coding assistants"
-- "Best practices for microservices architecture in fintech"</ask>
+<check if="{user_skill_level} == 'intermediate'">
+  "I'll help you create a structured research prompt for AI platforms like ChatGPT Deep Research, Gemini, or Grok.
 
-<template-output>research_topic</template-output>
+These tools work best with well-structured prompts that define scope, sources, and output format.
 
-<ask>What's your goal with this research?
+What do you want to research?"
+</check>
 
-- Strategic decision-making
-- Investment analysis
-- Academic paper/thesis
-- Product development
-- Market entry planning
-- Technical architecture decision
-- Competitive intelligence
-- Thought leadership content
-- Other (specify)</ask>
+<check if="{user_skill_level} == 'beginner'">
+  "Think of this as creating a detailed brief for an AI research assistant.
 
-<template-output>research_goal</template-output>
+Tools like ChatGPT Deep Research can spend hours searching the web and synthesizing information - but they work best when you give them clear instructions about what to look for and how to present it.
 
-<ask>Which AI platform will you use for the research?
+What topic are you curious about?"
+</check>
+</action>
+
+<action>Through conversation, discover:
+
+- **The research topic** - What they want to explore
+- **Their purpose** - Why they need this (decision-making, learning, writing, etc.)
+- **Target platform** - Which AI tool they'll use (affects prompt structure)
+- **Existing knowledge** - What they already know vs. what's uncertain
+
+Adapt your questions based on their clarity:
 
-1. ChatGPT Deep Research (o3/o1)
-2. Gemini Deep Research
-3. Grok DeepSearch
-4. Claude Projects
-5. Multiple platforms
-6. Not sure yet</ask>
+- If they're vague → Help them sharpen the focus
+- If they're specific → Capture the details
+- If they're unsure about platform → Guide them to the best fit
 
+Don't make them fill out a form - have a real conversation.
+</action>
+
+<template-output>research_topic</template-output>
+<template-output>research_goal</template-output>
 <template-output>target_platform</template-output>
 
 </step>
@@ -374,60 +390,50 @@ Select option (1-4):</ask>
 
 </step>
 
-<step n="FINAL" goal="Update status file on completion">
-<action>Search {output_folder}/ for files matching pattern: bmm-workflow-status.md</action>
-<action>Find the most recent file (by date in filename)</action>
+<step n="FINAL" 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-deep-prompt-{{date}}.md"</action>
+  <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
 
-<check if="status file exists">
-  <invoke-workflow path="{project-root}/bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: research</param>
-  </invoke-workflow>
-
-  <check if="success == true">
-    <output>Status updated! Next: {{next_workflow}}</output>
-  </check>
+<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>**✅ Deep Research Prompt Generated**
 
 **Research Prompt:**
 
-- Structured research prompt generated and saved
+- Structured research prompt generated and saved to {output_folder}/bmm-research-deep-prompt-{{date}}.md
 - Ready to execute with ChatGPT, Claude, Gemini, or Grok
 
-**Status file updated:**
+{{#if standalone_mode != true}}
+**Status Updated:**
 
-- Current step: research (deep-prompt) ✓
-- Progress: {{new_progress_percentage}}%
+- Progress tracking updated: research marked complete
+- Next workflow: {{next_workflow}}
+  {{else}}
+  **Note:** Running in standalone mode (no progress tracking)
+  {{/if}}
 
 **Next Steps:**
 
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
+{{#if standalone_mode != true}}
+
+- **Next workflow:** {{next_workflow}} ({{next_agent}} agent)
 - **Optional:** Execute the research prompt with AI platform, gather findings, or run additional research workflows
 
 Check status anytime with: `workflow-status`
-</output>
-</check>
-
-<check if="status file not found">
-  <output>**✅ Deep Research Prompt Generated**
-
-**Research Prompt:**
-
-- Structured research prompt generated and saved
-
-Note: Running in standalone mode (no status file).
-
-**Next Steps:**
-
+{{else}}
 Since no workflow is in progress:
 
 - Execute the research prompt with AI platform and gather 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>
-  </check>
   </step>
 
 </workflow>