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

package/src/modules/bmm/workflows/1-analysis/product-brief/template.md

@@ -2,7 +2,7 @@
 
 **Date:** {{date}}
 **Author:** {{user_name}}
-**Status:** Draft for PM Review
+**Context:** {{context_type}}
 
 ---
 
@@ -12,154 +12,170 @@
 
 ---
 
-## Problem Statement
+## Core Vision
+
+### Problem Statement
 
 {{problem_statement}}
 
----
+{{#if problem_impact}}
 
-## Proposed Solution
+### Problem Impact
 
-{{proposed_solution}}
+{{problem_impact}}
+{{/if}}
 
----
+{{#if existing_solutions_gaps}}
 
-## Target Users
+### Why Existing Solutions Fall Short
 
-### Primary User Segment
+{{existing_solutions_gaps}}
+{{/if}}
 
-{{primary_user_segment}}
+### Proposed Solution
 
-### Secondary User Segment
+{{proposed_solution}}
 
-{{secondary_user_segment}}
+{{#if key_differentiators}}
+
+### Key Differentiators
+
+{{key_differentiators}}
+{{/if}}
 
 ---
 
-## Goals and Success Metrics
+## Target Users
 
-### Business Objectives
+### Primary Users
 
-{{business_objectives}}
+{{primary_user_segment}}
 
-### User Success Metrics
+{{#if secondary_user_segment}}
 
-{{user_success_metrics}}
+### Secondary Users
 
-### Key Performance Indicators (KPIs)
+{{secondary_user_segment}}
+{{/if}}
 
-{{key_performance_indicators}}
+{{#if user_journey}}
+
+### User Journey
+
+{{user_journey}}
+{{/if}}
 
 ---
 
-## Strategic Alignment and Financial Impact
+{{#if success_metrics}}
 
-### Financial Impact
+## Success Metrics
 
-{{financial_impact}}
+{{success_metrics}}
 
-### Company Objectives Alignment
+{{#if business_objectives}}
 
-{{company_objectives_alignment}}
+### Business Objectives
+
+{{business_objectives}}
+{{/if}}
 
-### Strategic Initiatives
+{{#if key_performance_indicators}}
 
-{{strategic_initiatives}}
+### Key Performance Indicators
+
+{{key_performance_indicators}}
+{{/if}}
+{{/if}}
 
 ---
 
 ## MVP Scope
 
-### Core Features (Must Have)
+### Core Features
 
 {{core_features}}
 
+{{#if out_of_scope}}
+
 ### Out of Scope for MVP
 
 {{out_of_scope}}
+{{/if}}
+
+{{#if mvp_success_criteria}}
 
 ### MVP Success Criteria
 
 {{mvp_success_criteria}}
+{{/if}}
 
----
-
-## Post-MVP Vision
-
-### Phase 2 Features
-
-{{phase_2_features}}
-
-### Long-term Vision
-
-{{long_term_vision}}
+{{#if future_vision_features}}
 
-### Expansion Opportunities
+### Future Vision
 
-{{expansion_opportunities}}
+{{future_vision_features}}
+{{/if}}
 
 ---
 
-## Technical Considerations
+{{#if market_analysis}}
 
-### Platform Requirements
+## Market Context
 
-{{platform_requirements}}
+{{market_analysis}}
+{{/if}}
 
-### Technology Preferences
+{{#if financial_considerations}}
 
-{{technology_preferences}}
+## Financial Considerations
 
-### Architecture Considerations
+{{financial_considerations}}
+{{/if}}
 
-{{architecture_considerations}}
+{{#if technical_preferences}}
 
----
+## Technical Preferences
 
-## Constraints and Assumptions
+{{technical_preferences}}
+{{/if}}
 
-### Constraints
+{{#if organizational_context}}
 
-{{constraints}}
+## Organizational Context
 
-### Key Assumptions
+{{organizational_context}}
+{{/if}}
 
-{{key_assumptions}}
+{{#if risks_and_assumptions}}
 
----
+## Risks and Assumptions
 
-## Risks and Open Questions
+{{risks_and_assumptions}}
+{{/if}}
 
-### Key Risks
+{{#if timeline_constraints}}
 
-{{key_risks}}
+## Timeline
 
-### Open Questions
+{{timeline_constraints}}
+{{/if}}
 
-{{open_questions}}
+{{#if supporting_materials}}
 
-### Areas Needing Further Research
+## Supporting Materials
 
-{{research_areas}}
+{{supporting_materials}}
+{{/if}}
 
 ---
 
-## Appendices
-
-### A. Research Summary
-
-{{research_summary}}
-
-### B. Stakeholder Input
-
-{{stakeholder_input}}
-
-### C. References
-
-{{references}}
-
----
+_This Product Brief captures the vision and requirements for {{project_name}}._
 
-_This Product Brief serves as the foundational input for Product Requirements Document (PRD) creation._
+_It was created through collaborative discovery and reflects the unique needs of this {{context_type}} project._
 
-_Next Steps: Handoff to Product Manager for PRD development using the `workflow prd` command._
+{{#if next_workflow}}
+_Next: {{next_workflow}} will transform this brief into detailed planning artifacts._
+{{else}}
+_Next: Use the PRD workflow to create detailed product requirements from this brief._
+{{/if}}

package/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml

@@ -19,6 +19,20 @@ recommended_inputs:
   - competitive_analysis: "Competitive analysis (optional)"
   - initial_ideas: "Initial product ideas or notes (optional)"
 
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  research:
+    whole: "{output_folder}/*research*.md"
+    sharded: "{output_folder}/*research*/index.md"
+
+  brainstorming:
+    whole: "{output_folder}/*brainstorm*.md"
+    sharded: "{output_folder}/*brainstorm*/index.md"
+
+  document_project:
+    sharded: "{output_folder}/docs/index.md"
+
 # Module path and component files
 installed_path: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief"
 template: "{installed_path}/template.md"

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

@@ -0,0 +1,144 @@
+# Deep Research Prompt Validation Checklist
+
+## 🚨 CRITICAL: Anti-Hallucination Instructions (PRIORITY)
+
+### Citation Requirements Built Into Prompt
+
+- [ ] Prompt EXPLICITLY instructs: "Cite sources with URLs for ALL factual claims"
+- [ ] Prompt requires: "Include source name, date, and URL for every statistic"
+- [ ] Prompt mandates: "If you cannot find reliable data, state 'No verified data found for [X]'"
+- [ ] Prompt specifies inline citation format (e.g., "[Source: Company, Year, URL]")
+- [ ] Prompt requires References section at end with all sources listed
+
+### Multi-Source Verification Requirements
+
+- [ ] Prompt instructs: "Cross-reference critical claims with at least 2 independent sources"
+- [ ] Prompt requires: "Note when sources conflict and present all viewpoints"
+- [ ] Prompt specifies: "Verify version numbers and dates from official sources"
+- [ ] Prompt mandates: "Mark confidence levels: [Verified], [Single source], [Uncertain]"
+
+### Fact vs Analysis Distinction
+
+- [ ] Prompt requires clear labeling: "Distinguish FACTS (sourced), ANALYSIS (your interpretation), SPECULATION (projections)"
+- [ ] Prompt instructs: "Do not present assumptions or analysis as verified facts"
+- [ ] Prompt requires: "Label projections and forecasts clearly as such"
+- [ ] Prompt warns: "Avoid vague attributions like 'experts say' - name the expert/source"
+
+### Source Quality Guidance
+
+- [ ] Prompt specifies preferred sources (e.g., "Official docs > analyst reports > blog posts")
+- [ ] Prompt prioritizes recency: "Prioritize {{current_year}} sources for time-sensitive data"
+- [ ] Prompt requires credibility assessment: "Note source credibility for each citation"
+- [ ] Prompt warns against: "Do not rely on single blog posts for critical claims"
+
+### Anti-Hallucination Safeguards
+
+- [ ] Prompt warns: "If data seems convenient or too round, verify with additional sources"
+- [ ] Prompt instructs: "Flag suspicious claims that need third-party verification"
+- [ ] Prompt requires: "Provide date accessed for all web sources"
+- [ ] Prompt mandates: "Do NOT invent statistics - only use verified data"
+
+## Prompt Foundation
+
+### Topic and Scope
+
+- [ ] Research topic is specific and focused (not too broad)
+- [ ] Target platform is specified (ChatGPT, Gemini, Grok, Claude)
+- [ ] Temporal scope defined and includes "current {{current_year}}" requirement
+- [ ] Source recency requirement specified (e.g., "prioritize 2024-2025 sources")
+
+## Content Requirements
+
+### Information Specifications
+
+- [ ] Types of information needed are listed (quantitative, qualitative, trends, case studies, etc.)
+- [ ] Preferred sources are specified (academic, industry reports, news, etc.)
+- [ ] Recency requirements are stated (e.g., "prioritize {{current_year}} sources")
+- [ ] Keywords and technical terms are included for search optimization
+- [ ] Validation criteria are defined (how to verify findings)
+
+### Output Structure
+
+- [ ] Desired format is clear (executive summary, comparison table, timeline, SWOT, etc.)
+- [ ] Key sections or questions are outlined
+- [ ] Depth level is specified (overview, standard, comprehensive, exhaustive)
+- [ ] Citation requirements are stated
+- [ ] Any special formatting needs are mentioned
+
+## Platform Optimization
+
+### Platform-Specific Elements
+
+- [ ] Prompt is optimized for chosen platform's capabilities
+- [ ] Platform-specific tips are included
+- [ ] Query limit considerations are noted (if applicable)
+- [ ] Platform strengths are leveraged (e.g., ChatGPT's multi-step search, Gemini's plan modification)
+
+### Execution Guidance
+
+- [ ] Research persona/perspective is specified (if applicable)
+- [ ] Special requirements are stated (bias considerations, recency, etc.)
+- [ ] Follow-up strategy is outlined
+- [ ] Validation approach is defined
+
+## Quality and Usability
+
+### Clarity and Completeness
+
+- [ ] Prompt language is clear and unambiguous
+- [ ] All placeholders and variables are replaced with actual values
+- [ ] Prompt can be copy-pasted directly into platform
+- [ ] No contradictory instructions exist
+- [ ] Prompt is self-contained (doesn't assume unstated context)
+
+### Practical Utility
+
+- [ ] Execution checklist is provided (before, during, after research)
+- [ ] Platform usage tips are included
+- [ ] Follow-up questions are anticipated
+- [ ] Success criteria are defined
+- [ ] Output file format is specified
+
+## Research Depth
+
+### Scope Appropriateness
+
+- [ ] Scope matches user's available time and resources
+- [ ] Depth is appropriate for decision at hand
+- [ ] Key questions that MUST be answered are identified
+- [ ] Nice-to-have vs. critical information is distinguished
+
+## Validation Criteria
+
+### Quality Standards
+
+- [ ] Method for cross-referencing sources is specified
+- [ ] Approach to handling conflicting information is defined
+- [ ] Confidence level indicators are requested
+- [ ] Gap identification is included
+- [ ] Fact vs. opinion distinction is required
+
+---
+
+## Issues Found
+
+### Critical Issues
+
+_List any critical gaps or errors that must be addressed:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Minor Improvements
+
+_List minor improvements that would enhance the prompt:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+---
+
+**Validation Complete:** ☐ Yes ☐ No
+**Ready to Execute:** ☐ Yes ☐ No
+**Reviewer:** \***\*\_\*\***
+**Date:** \***\*\_\*\***

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

@@ -0,0 +1,249 @@
+# Technical/Architecture Research Validation Checklist
+
+## 🚨 CRITICAL: Source Verification and Fact-Checking (PRIORITY)
+
+### Version Number Verification (MANDATORY)
+
+- [ ] **EVERY** technology version number has cited source with URL
+- [ ] Version numbers verified via WebSearch from {{current_year}} (NOT from training data!)
+- [ ] Official documentation/release pages cited for each version
+- [ ] Release dates included with version numbers
+- [ ] LTS status verified from official sources (with URL)
+- [ ] No "assumed" or "remembered" version numbers - ALL must be verified
+
+### Technical Claim Source Verification
+
+- [ ] **EVERY** feature claim has source (official docs, release notes, website)
+- [ ] Performance benchmarks cite source (official benchmarks, third-party tests with URLs)
+- [ ] Compatibility claims verified (official compatibility matrix, documentation)
+- [ ] Community size/popularity backed by sources (GitHub stars, npm downloads, official stats)
+- [ ] "Supports X" claims verified via official documentation with URL
+- [ ] No invented capabilities or features
+
+### Source Quality for Technical Data
+
+- [ ] Official documentation prioritized (docs.technology.com > blog posts)
+- [ ] Version info from official release pages (highest credibility)
+- [ ] Benchmarks from official sources or reputable third-parties (not random blogs)
+- [ ] Community data from verified sources (GitHub, npm, official registries)
+- [ ] Pricing from official pricing pages (with URL and date verified)
+
+### Multi-Source Verification (Critical Technical Claims)
+
+- [ ] Major technical claims (performance, scalability) verified by 2+ sources
+- [ ] Technology comparisons cite multiple independent sources
+- [ ] "Best for X" claims backed by comparative analysis with sources
+- [ ] Production experience claims cite real case studies or articles with URLs
+- [ ] No single-source critical decisions without flagging need for verification
+
+### Anti-Hallucination for Technical Data
+
+- [ ] No invented version numbers or release dates
+- [ ] No assumed feature availability without verification
+- [ ] If current data not found, explicitly states "Could not verify {{current_year}} information"
+- [ ] Speculation clearly labeled (e.g., "Based on trends, technology may...")
+- [ ] No "probably supports" or "likely compatible" without verification
+
+## Technology Evaluation
+
+### Comprehensive Profiling
+
+For each evaluated technology:
+
+- [ ] Core capabilities and features are documented
+- [ ] Architecture and design philosophy are explained
+- [ ] Maturity level is assessed (experimental, stable, mature, legacy)
+- [ ] Community size and activity are measured
+- [ ] Maintenance status is verified (active, maintenance mode, abandoned)
+
+### Practical Considerations
+
+- [ ] Learning curve is evaluated
+- [ ] Documentation quality is assessed
+- [ ] Developer experience is considered
+- [ ] Tooling ecosystem is reviewed
+- [ ] Testing and debugging capabilities are examined
+
+### Operational Assessment
+
+- [ ] Deployment complexity is understood
+- [ ] Monitoring and observability options are evaluated
+- [ ] Operational overhead is estimated
+- [ ] Cloud provider support is verified
+- [ ] Container/Kubernetes compatibility is checked (if relevant)
+
+## Comparative Analysis
+
+### Multi-Dimensional Comparison
+
+- [ ] Technologies are compared across relevant dimensions
+- [ ] Performance benchmarks are included (if available)
+- [ ] Scalability characteristics are compared
+- [ ] Complexity trade-offs are analyzed
+- [ ] Total cost of ownership is estimated for each option
+
+### Trade-off Analysis
+
+- [ ] Key trade-offs between options are identified
+- [ ] Decision factors are prioritized based on user needs
+- [ ] Conditions favoring each option are specified
+- [ ] Weighted analysis reflects user's priorities
+
+## Real-World Evidence
+
+### Production Experience
+
+- [ ] Real-world production experiences are researched
+- [ ] Known issues and gotchas are documented
+- [ ] Performance data from actual deployments is included
+- [ ] Migration experiences are considered (if replacing existing tech)
+- [ ] Community discussions and war stories are referenced
+
+### Source Quality
+
+- [ ] Multiple independent sources validate key claims
+- [ ] Recent sources from {{current_year}} are prioritized
+- [ ] Practitioner experiences are included (blog posts, conference talks, forums)
+- [ ] Both proponent and critic perspectives are considered
+
+## Decision Support
+
+### Recommendations
+
+- [ ] Primary recommendation is clearly stated with rationale
+- [ ] Alternative options are explained with use cases
+- [ ] Fit for user's specific context is explained
+- [ ] Decision is justified by requirements and constraints
+
+### Implementation Guidance
+
+- [ ] Proof-of-concept approach is outlined
+- [ ] Key implementation decisions are identified
+- [ ] Migration path is described (if applicable)
+- [ ] Success criteria are defined
+- [ ] Validation approach is recommended
+
+### Risk Management
+
+- [ ] Technical risks are identified
+- [ ] Mitigation strategies are provided
+- [ ] Contingency options are outlined (if primary choice doesn't work)
+- [ ] Exit strategy considerations are discussed
+
+## Architecture Decision Record
+
+### ADR Completeness
+
+- [ ] Status is specified (Proposed, Accepted, Superseded)
+- [ ] Context and problem statement are clear
+- [ ] Decision drivers are documented
+- [ ] All considered options are listed
+- [ ] Chosen option and rationale are explained
+- [ ] Consequences (positive, negative, neutral) are identified
+- [ ] Implementation notes are included
+- [ ] References to research sources are provided
+
+## References and Source Documentation (CRITICAL)
+
+### References Section Completeness
+
+- [ ] Report includes comprehensive "References and Sources" section
+- [ ] Sources organized by category (official docs, benchmarks, community, architecture)
+- [ ] Every source includes: Title, Publisher/Site, Date Accessed, Full URL
+- [ ] URLs are clickable and functional (documentation links, release pages, GitHub)
+- [ ] Version verification sources clearly listed
+- [ ] Inline citations throughout report reference the sources section
+
+### Technology Source Documentation
+
+- [ ] For each technology evaluated, sources documented:
+  - Official documentation URL
+  - Release notes/changelog URL for version
+  - Pricing page URL (if applicable)
+  - Community/GitHub URL
+  - Benchmark source URLs
+- [ ] Comparison data cites source for each claim
+- [ ] Architecture pattern sources cited (articles, books, official guides)
+
+### Source Quality Metrics
+
+- [ ] Report documents total sources cited
+- [ ] Official sources count (highest credibility)
+- [ ] Third-party sources count (benchmarks, articles)
+- [ ] Version verification count (all technologies verified {{current_year}})
+- [ ] Outdated sources flagged (if any used)
+
+### Citation Format Standards
+
+- [ ] Inline citations format: [Source: Docs URL] or [Version: 1.2.3, Source: Release Page URL]
+- [ ] Consistent citation style throughout
+- [ ] No vague citations like "according to the community" without specifics
+- [ ] GitHub links include star count and last update date
+- [ ] Documentation links point to current stable version docs
+
+## Document Quality
+
+### Anti-Hallucination Final Check
+
+- [ ] Spot-check 5 random version numbers - can you find the cited source?
+- [ ] Verify feature claims against official documentation
+- [ ] Check any performance numbers have benchmark sources
+- [ ] Ensure no "cutting edge" or "latest" without specific version number
+- [ ] Cross-check technology comparisons with cited sources
+
+### Structure and Completeness
+
+- [ ] Executive summary captures key findings
+- [ ] No placeholder text remains (all {{variables}} are replaced)
+- [ ] References section is complete and properly formatted
+- [ ] Version verification audit trail included
+- [ ] Document ready for technical fact-checking by third party
+
+## Research Completeness
+
+### Coverage
+
+- [ ] All user requirements were addressed
+- [ ] All constraints were considered
+- [ ] Sufficient depth for the decision at hand
+- [ ] Optional analyses were considered and included/excluded appropriately
+- [ ] Web research was conducted for current market data
+
+### Data Freshness
+
+- [ ] Current {{current_year}} data was used throughout
+- [ ] Version information is up-to-date
+- [ ] Recent developments and trends are included
+- [ ] Outdated or deprecated information is flagged or excluded
+
+---
+
+## Issues Found
+
+### Critical Issues
+
+_List any critical gaps or errors that must be addressed:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Minor Improvements
+
+_List minor improvements that would enhance the report:_
+
+- [ ] Issue 1: [Description]
+- [ ] Issue 2: [Description]
+
+### Additional Research Needed
+
+_List areas requiring further investigation:_
+
+- [ ] Topic 1: [Description]
+- [ ] Topic 2: [Description]
+
+---
+
+**Validation Complete:** ☐ Yes ☐ No
+**Ready for Decision:** ☐ Yes ☐ No
+**Reviewer:** \***\*\_\*\***
+**Date:** \***\*\_\*\***