pig-farm-controller/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 conducts technical research for architecture and technology decisions

Understand the technical research requirements

Welcome to Technical/Architecture Research!

What technical decision or research do you need?

Common scenarios:

• Evaluate technology stack for a new project
• Compare frameworks or libraries (React vs Vue, Postgres vs MongoDB)
• Research architecture patterns (microservices, event-driven, CQRS)
• Investigate specific technologies or tools
• Best practices for specific use cases
• Performance and scalability considerations
• Security and compliance research

technical_question

What's the context for this decision?

• New greenfield project
• Adding to existing system (brownfield)
• Refactoring/modernizing legacy system
• Proof of concept / prototype
• Production-ready implementation
• Academic/learning purpose

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

Research and identify technology options to evaluate

Do you have specific technologies in mind to compare, or should I discover options?

If you have specific options, list them. Otherwise, I'll research current leading solutions based on your requirements.

user_provided_options

Conduct web research to identify current leading solutions Search for:

• "[technical_category] best tools 2025"

• "[technical_category] comparison [use_case]"

• "[technical_category] production experiences reddit"

• "State of [technical_category] 2025"

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

Present discovered options (typically 3-5 main candidates) technology_options

Research each technology option in depth

For each technology option, research thoroughly

Research and document:

Overview:

• What is it and what problem does it solve?
• Maturity level (experimental, stable, mature, legacy)
• Community size and activity
• Maintenance status and 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}}