LMS-BGN/.bmad/bmm/workflows/1-analysis/research/instructions-technical.md

Technical/Architecture Research Instructions

The workflow execution engine is governed by: {project_root}/.bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {installed_path}/workflow.yaml This workflow uses ADAPTIVE FACILITATION - adjust your communication style based on {user_skill_level} This is a HIGHLY INTERACTIVE workflow - make technical decisions WITH user, not FOR them Web research is MANDATORY - use WebSearch tool with {{current_year}} for current version info and trends ALWAYS verify current versions - NEVER use hardcoded or outdated version numbers Communicate all responses in {communication_language} and tailor to {user_skill_level} Generate all documents in {document_output_language}

🚨 ANTI-HALLUCINATION PROTOCOL - MANDATORY 🚨 NEVER invent version numbers, features, or technical details - ALWAYS verify with current {{current_year}} sources Every technical claim (version, feature, performance, compatibility) MUST have a cited source with URL Version numbers MUST be verified via WebSearch - do NOT rely on training data (it's outdated!) When comparing technologies, cite sources for each claim (performance benchmarks, community size, etc.) Mark confidence levels: [Verified {{current_year}} source], [Older source - verify], [Uncertain - needs verification] Distinguish: FACT (from official docs/sources), OPINION (from community/reviews), SPECULATION (your analysis) If you cannot find current information about a technology, state: "I could not find recent {{current_year}} data on [X]" Extract and include source URLs in all technology profiles and comparisons

Engage conversationally based on skill level:

"Let's research the technical options for your decision.

I'll gather current data from {{current_year}}, compare approaches, and help you think through trade-offs.

What technical question are you wrestling with?"

"I'll help you research and evaluate your technical options.

We'll look at current technologies (using {{current_year}} data), understand the trade-offs, and figure out what fits your needs best.

What technical decision are you trying to make?"

"Think of this as having a technical advisor help you research your options.

I'll explain what different technologies do, why you might choose one over another, and help you make an informed decision.

What technical challenge brought you here?"

Through conversation, understand:

• The technical question - What they need to decide or understand
• The context - Greenfield? Brownfield? Learning? Production?
• Current constraints - Languages, platforms, team skills, budget
• What they already know - Do they have candidates in mind?

Don't interrogate - explore together. If they're unsure, help them articulate the problem.

technical_question project_context

Gather requirements and constraints that will guide the research

Let's define your technical requirements:

Functional Requirements - What must the technology do?

Examples:

• Handle 1M requests per day
• Support real-time data processing
• Provide full-text search capabilities
• Enable offline-first mobile app
• Support multi-tenancy

functional_requirements

Non-Functional Requirements - Performance, scalability, security needs?

Consider:

• Performance targets (latency, throughput)
• Scalability requirements (users, data volume)
• Reliability and availability needs
• Security and compliance requirements
• Maintainability and developer experience

non_functional_requirements

Constraints - What limitations or requirements exist?

• Programming language preferences or requirements
• Cloud platform (AWS, Azure, GCP, on-prem)
• Budget constraints
• Team expertise and skills
• Timeline and urgency
• Existing technology stack (if brownfield)
• Open source vs commercial requirements
• Licensing considerations

technical_constraints

MUST use WebSearch to find current options from {{current_year}}

Ask if they have candidates in mind:

"Do you already have specific technologies you want to compare, or should I search for the current options?"

Great! Let's research: {{user_candidates}}

Search for current leading technologies:

{{technical_category}} best tools {{current_year}} {{technical_category}} comparison {{use_case}} {{current_year}} {{technical_category}} popular frameworks {{current_year}} state of {{technical_category}} {{current_year}}

Share findings conversationally:

"Based on current {{current_year}} data, here are the main options:

{{discovered_options}}

These are the leaders right now. Which ones make sense to evaluate for your use case?" Each of these is popular for different reasons. Let me know if you want me to explain what makes each one different."

{project-root}/.bmad/core/tasks/adv-elicit.xml

technology_options

For each option, use WebSearch to gather CURRENT {{current_year}} information

For {{technology_name}}, conduct comprehensive research:

{{technology_name}} overview what is {{current_year}} {{technology_name}} latest version release notes {{current_year}} {{technology_name}} pros cons trade-offs {{current_year}} {{technology_name}} production experience real world {{current_year}} {{technology_name}} vs alternatives comparison {{current_year}}

Share findings conversationally and collaboratively:

"Here's what I found about {{technology_name}}:

Overview: {{what_it_is_and_solves}}

Current Status ({{current_year}}): {{maturity_community_release_cadence}}

Technical Characteristics:

• Architecture and design philosophy
• Core features and capabilities
• Performance characteristics
• Scalability approach
• Integration capabilities

Developer Experience:

• Learning curve
• Documentation quality
• Tooling ecosystem
• Testing support
• Debugging capabilities

Operations:

• Deployment complexity
• Monitoring and observability
• Operational overhead
• Cloud provider support
• Container/K8s compatibility

Ecosystem:

• Available libraries and plugins
• Third-party integrations
• Commercial support options
• Training and educational resources

Community and Adoption:

• GitHub stars/contributors (if applicable)
• Production usage examples
• Case studies from similar use cases
• Community support channels
• Job market demand

Costs:

• Licensing model
• Hosting/infrastructure costs
• Support costs
• Training costs
• Total cost of ownership estimate

{project-root}/.bmad/core/tasks/adv-elicit.xml techprofile{{option_number}}

Create structured comparison across all options

Create comparison matrices:

Generate comparison table with key dimensions:

Comparison Dimensions:

1. Meets Requirements - How well does each meet functional requirements?
2. Performance - Speed, latency, throughput benchmarks
3. Scalability - Horizontal/vertical scaling capabilities
4. Complexity - Learning curve and operational complexity
5. Ecosystem - Maturity, community, libraries, tools
6. Cost - Total cost of ownership
7. Risk - Maturity, vendor lock-in, abandonment risk
8. Developer Experience - Productivity, debugging, testing
9. Operations - Deployment, monitoring, maintenance
10. Future-Proofing - Roadmap, innovation, sustainability

Rate each option on relevant dimensions (High/Medium/Low or 1-5 scale)

comparative_analysis

Analyze trade-offs between options

Identify key trade-offs:

For each pair of leading options, identify trade-offs:

• What do you gain by choosing Option A over Option B?
• What do you sacrifice?
• Under what conditions would you choose one vs the other?

Decision factors by priority:

What are your top 3 decision factors?

Examples:

• Time to market
• Performance
• Developer productivity
• Operational simplicity
• Cost efficiency
• Future flexibility
• Team expertise match
• Community and support

decision_priorities

Weight the comparison analysis by decision priorities

weighted_analysis

Evaluate fit for specific use case

Match technologies to your specific use case:

Based on:

• Your functional and non-functional requirements
• Your constraints (team, budget, timeline)
• Your context (greenfield vs brownfield)
• Your decision priorities

Analyze which option(s) best fit your specific scenario.

Are there any specific concerns or "must-haves" that would immediately eliminate any options?

use_case_fit

Gather production experience evidence

Search for real-world experiences:

For top 2-3 candidates:

• Production war stories and lessons learned
• Known issues and gotchas
• Migration experiences (if replacing existing tech)
• Performance benchmarks from real deployments
• Team scaling experiences
• Reddit/HackerNews discussions
• Conference talks and blog posts from practitioners

real_world_evidence

If researching architecture patterns, provide pattern analysis

Are you researching architecture patterns (microservices, event-driven, etc.)?

Research and document:

Pattern Overview:

• Core principles and concepts
• When to use vs when not to use
• Prerequisites and foundations

Implementation Considerations:

• Technology choices for the pattern
• Reference architectures
• Common pitfalls and anti-patterns
• Migration path from current state

Trade-offs:

• Benefits and drawbacks
• Complexity vs benefits analysis
• Team skill requirements
• Operational overhead

architecture_pattern_analysis

Synthesize research into clear recommendations

Generate recommendations:

Top Recommendation:

• Primary technology choice with rationale
• Why it best fits your requirements and constraints
• Key benefits for your use case
• Risks and mitigation strategies

Alternative Options:

• Second and third choices
• When you might choose them instead
• Scenarios where they would be better

Implementation Roadmap:

• Proof of concept approach
• Key decisions to make during implementation
• Migration path (if applicable)
• Success criteria and validation approach

Risk Mitigation:

• Identified risks and mitigation plans
• Contingency options if primary choice doesn't work
• Exit strategy considerations

{project-root}/.bmad/core/tasks/adv-elicit.xml

recommendations

Create architecture decision record (ADR) template

Generate Architecture Decision Record:

Create ADR format documentation:

# ADR-XXX: [Decision Title]

## Status

[Proposed | Accepted | Superseded]

## Context

[Technical context and problem statement]

## Decision Drivers

[Key factors influencing the decision]

## Considered Options

[Technologies/approaches evaluated]

## Decision

[Chosen option and rationale]

## Consequences

**Positive:**

- [Benefits of this choice]

**Negative:**

- [Drawbacks and risks]

**Neutral:**

- [Other impacts]

## Implementation Notes

[Key considerations for implementation]

## References

[Links to research, benchmarks, case studies]

architecture_decision_record

Compile complete technical research report

Your Technical Research Report includes:

1. Executive Summary - Key findings and recommendation
2. Requirements and Constraints - What guided the research
3. Technology Options - All candidates evaluated
4. Detailed Profiles - Deep dive on each option
5. Comparative Analysis - Side-by-side comparison
6. Trade-off Analysis - Key decision factors
7. Real-World Evidence - Production experiences
8. Recommendations - Detailed recommendation with rationale
9. Architecture Decision Record - Formal decision documentation
10. Next Steps - Implementation roadmap

Save complete report to {default_output_file}

Would you like to:

1. Deep dive into specific technology
2. Research implementation patterns for chosen technology
3. Generate proof-of-concept plan
4. Create deep research prompt for ongoing investigation
5. Exit workflow

Select option (1-5):

LOAD: {installed_path}/instructions-deep-prompt.md Pre-populate with technical research context Load the FULL file: {output_folder}/bmm-workflow-status.yaml Find workflow_status key "research" ONLY write the file path as the status value - no other text, notes, or metadata Update workflow_status["research"] = "{output_folder}/bmm-research-technical-{{date}}.md" Save file, preserving ALL comments and structure including STATUS DEFINITIONS

Find first non-completed workflow in workflow_status (next workflow to do) Determine next agent from path file based on next workflow

✅ Technical Research Complete

Research Report:

• Technical research report generated and saved to {output_folder}/bmm-research-technical-{{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 architecture team, or run additional analysis workflows

Check status anytime with: workflow-status {{else}} Since no workflow is in progress:

• Review technical 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}}