20 KiB

Raw Blame History

BMM Solutioning Workflows (Phase 3)

Reading Time: ~8 minutes

Overview

Phase 3 (Solutioning) workflows translate what to build (from Planning) into how to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.

Key principle: Make technical decisions explicit and documented so all agents implement consistently. Prevent one agent choosing REST while another chooses GraphQL.

Required for: BMad Method (complex projects), Enterprise Method

Optional for: BMad Method (simple projects), Quick Flow (skip entirely)

Phase 3 Solutioning Workflow Map

%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
    FromPlanning["<b>FROM Phase 2 Planning</b><br/>PRD (FRs/NFRs) complete"]

    subgraph QuickFlow["<b>QUICK FLOW PATH</b>"]
        direction TB
        SkipArch["<b>Skip Phase 3</b><br/>Go directly to Implementation"]
    end

    subgraph BMadEnterprise["<b>BMAD METHOD + ENTERPRISE (Same Start)</b>"]
        direction TB
        OptionalUX["<b>UX Designer: create-ux-design</b><br/>(Optional)"]
        Architecture["<b>Architect: architecture</b><br/>System design + ADRs"]

        subgraph Optional["<b>ENTERPRISE ADDITIONS (Optional)</b>"]
            direction LR
            SecArch["<b>Architect: security-architecture</b><br/>(Future)"]
            DevOps["<b>Architect: devops-strategy</b><br/>(Future)"]
        end

        EpicsStories["<b>PM: create-epics-and-stories</b><br/>Break down FRs/NFRs into epics"]
        GateCheck["<b>Architect: implementation-readiness</b><br/>Validation before Phase 4"]

        OptionalUX -.-> Architecture
        Architecture -.->|Enterprise only| Optional
        Architecture --> EpicsStories
        Optional -.-> EpicsStories
        EpicsStories --> GateCheck
    end

    subgraph Result["<b>GATE CHECK RESULTS</b>"]
        direction LR
        Pass["✅ PASS<br/>Proceed to Phase 4"]
        Concerns["⚠️ CONCERNS<br/>Proceed with caution"]
        Fail["❌ FAIL<br/>Resolve issues first"]
    end

    FromPlanning -->|Quick Flow| QuickFlow
    FromPlanning -->|BMad Method<br/>or Enterprise| OptionalUX

    QuickFlow --> Phase4["<b>Phase 4: Implementation</b>"]
    GateCheck --> Result
    Pass --> Phase4
    Concerns --> Phase4
    Fail -.->|Fix issues| Architecture

    style FromPlanning fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px,color:#000
    style QuickFlow fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
    style BMadEnterprise fill:#90caf9,stroke:#0d47a1,stroke-width:3px,color:#000
    style Optional fill:#ffcdd2,stroke:#c62828,stroke-width:3px,color:#000
    style Result fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
    style Phase4 fill:#ffcc80,stroke:#e65100,stroke-width:2px,color:#000

    style SkipArch fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
    style OptionalUX fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000
    style Architecture fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
    style SecArch fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
    style DevOps fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
    style EpicsStories fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
    style GateCheck fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
    style Pass fill:#81c784,stroke:#388e3c,stroke-width:2px,color:#000
    style Concerns fill:#ffb74d,stroke:#f57f17,stroke-width:2px,color:#000
    style Fail fill:#e57373,stroke:#d32f2f,stroke-width:2px,color:#000

Quick Reference

Workflow	Agent	Track	Purpose
create-ux-design	UX Designer	BMad Method, Enterprise	Optional UX design (after PRD, before arch)
architecture	Architect	BMad Method, Enterprise	Technical architecture and design decisions
create-epics-and-stories	PM	BMad Method, Enterprise	Break FRs/NFRs into epics after architecture
implementation-readiness	Architect	BMad Complex, Enterprise	Validate planning/solutioning completeness

When to Skip Solutioning:

Quick Flow: Simple changes don't need architecture → Skip to Phase 4

When Solutioning is Required:

BMad Method: Multi-epic projects need architecture to prevent conflicts
Enterprise: Same as BMad Method, plus optional extended workflows (test architecture, security architecture, devops strategy) added AFTER architecture but BEFORE gate check

Why Solutioning Matters

The Problem Without Solutioning

Agent 1 implements Epic 1 using REST API
Agent 2 implements Epic 2 using GraphQL
Result: Inconsistent API design, integration nightmare

The Solution With Solutioning

architecture workflow decides: "Use GraphQL for all APIs"
All agents follow architecture decisions
Result: Consistent implementation, no conflicts

Solutioning vs Planning

Aspect	Planning (Phase 2)	Solutioning (Phase 3)
Question	What and Why?	How? Then What units of work?
Output	FRs/NFRs (Requirements)	Architecture + Epics/Stories
Agent	PM	Architect → PM
Audience	Stakeholders	Developers
Document	PRD (FRs/NFRs)	Architecture + Epic Files
Level	Business logic	Technical design + Work breakdown

Workflow Descriptions

architecture

Purpose: Make technical decisions explicit to prevent agent conflicts. Produces decision-focused architecture document optimized for AI consistency.

Agent: Architect

When to Use:

Multi-epic projects (BMad Complex, Enterprise)
Cross-cutting technical concerns
Multiple agents implementing different parts
Integration complexity exists
Technology choices need alignment

When to Skip:

Quick Flow (simple changes)
BMad Method Simple with straightforward tech stack
Single epic with clear technical approach

Adaptive Conversation Approach:

This is NOT a template filler. The architecture workflow:

Discovers technical needs through conversation
Proposes architectural options with trade-offs
Documents decisions that prevent agent conflicts
Focuses on decision points, not exhaustive documentation

Key Outputs:

architecture.md containing:

Architecture Overview - System context, principles, style
System Architecture - High-level diagram, component interactions, communication patterns
Data Architecture - Database design, state management, caching, data flow
API Architecture - API style (REST/GraphQL/gRPC), auth, versioning, error handling
Frontend Architecture (if applicable) - Framework, state management, component architecture, routing
Integration Architecture - Third-party integrations, message queuing, event-driven patterns
Security Architecture - Auth/authorization, data protection, security boundaries
Deployment Architecture - Deployment model, CI/CD, environment strategy, monitoring
Architecture Decision Records (ADRs) - Key decisions with context, options, trade-offs, rationale
FR/NFR-Specific Guidance - Technical approach per functional requirement, implementation priorities, dependencies
Standards and Conventions - Directory structure, naming conventions, code organization, testing

ADR Format (Brief):

## ADR-001: Use GraphQL for All APIs

**Status:** Accepted | **Date:** 2025-11-02

**Context:** PRD requires flexible querying across multiple epics

**Decision:** Use GraphQL for all client-server communication

**Options Considered:**

1. REST - Familiar but requires multiple endpoints
2. GraphQL - Flexible querying, learning curve
3. gRPC - High performance, poor browser support

**Rationale:**

- PRD requires flexible data fetching (Epic 1, 3)
- Mobile app needs bandwidth optimization (Epic 2)
- Team has GraphQL experience

**Consequences:**

- Positive: Flexible querying, reduced versioning
- Negative: Caching complexity, N+1 query risk
- Mitigation: Use DataLoader for batching

**Implications for FRs:**

- FR-001: User Management → GraphQL mutations
- FR-002: Mobile App → Optimized queries

Example: E-commerce platform → Monolith + PostgreSQL + Redis + Next.js + GraphQL, with ADRs explaining each choice and FR/NFR-specific guidance.

Integration: Feeds into create-epics-and-stories workflow. Architecture provides the technical context needed for breaking FRs/NFRs into implementable epics and stories. All dev agents reference architecture during Phase 4 implementation.

create-epics-and-stories

Purpose: Transform PRD's functional and non-functional requirements into bite-sized stories organized into deliverable functional epics. This workflow runs AFTER architecture so epics/stories are informed by technical decisions.

Agent: PM (Product Manager)

When to Use:

After architecture workflow completes
When PRD contains FRs/NFRs ready for implementation breakdown
Before implementation-readiness gate check

Key Inputs:

PRD (FRs/NFRs) from Phase 2 Planning
architecture.md with ADRs and technical decisions
Optional: UX design artifacts

Why After Architecture:

The create-epics-and-stories workflow runs AFTER architecture because:

Informed Story Sizing: Architecture decisions (database choice, API style, etc.) affect story complexity
Dependency Awareness: Architecture reveals technical dependencies between stories
Technical Feasibility: Stories can be properly scoped knowing the tech stack
Consistency: All stories align with documented architectural patterns

Key Outputs:

Epic files (one per epic) containing:

Epic objective and scope
User stories with acceptance criteria
Story priorities (P0/P1/P2/P3)
Dependencies between stories
Technical notes referencing architecture decisions

Example: E-commerce PRD with FR-001 (User Registration), FR-002 (Product Catalog) → Epic 1: User Management (3 stories), Epic 2: Product Display (4 stories), each story referencing relevant ADRs.

implementation-readiness

Purpose: Systematically validate that planning and solutioning are complete and aligned before Phase 4 implementation. Ensures PRD, architecture, and epics are cohesive with no gaps.

Agent: Architect

When to Use:

Always before Phase 4 for BMad Complex and Enterprise projects
After create-epics-and-stories workflow completes
Before sprint-planning workflow
When stakeholders request readiness check

When to Skip:

Quick Flow (no solutioning)
BMad Simple (no gate check required)

Purpose of Gate Check:

Prevents:

❌ Architecture doesn't address all FRs/NFRs
❌ Epics conflict with architecture decisions
❌ Requirements ambiguous or contradictory
❌ Missing critical dependencies

Ensures:

✅ PRD → Architecture → Epics alignment
✅ All epics have clear technical approach
✅ No contradictions or gaps
✅ Team ready to implement

Check Criteria:

PRD/GDD Completeness:

Problem statement clear and evidence-based
Success metrics defined
User personas identified
Functional requirements (FRs) complete
Non-functional requirements (NFRs) specified
Risks and assumptions documented

Architecture Completeness:

System architecture defined
Data architecture specified
API architecture decided
Key ADRs documented
Security architecture addressed
FR/NFR-specific guidance provided
Standards and conventions defined

Epic/Story Completeness:

All PRD features mapped to stories
Stories have acceptance criteria
Stories prioritized (P0/P1/P2/P3)
Dependencies identified
Story sequencing logical

Alignment Checks:

Architecture addresses all PRD FRs/NFRs
Epics align with architecture decisions
No contradictions between epics
NFRs have technical approach
Integration points clear

Gate Decision Logic:

✅ PASS

All critical criteria met
Minor gaps acceptable with documented plan
Action: Proceed to Phase 4

⚠️ CONCERNS

Some criteria not met but not blockers
Gaps identified with clear resolution path
Action: Proceed with caution, address gaps in parallel

❌ FAIL

Critical gaps or contradictions
Architecture missing key decisions
Epics conflict with PRD/architecture
Action: BLOCK Phase 4, resolve issues first

Key Outputs:

implementation-readiness.md containing:

Executive Summary (PASS/CONCERNS/FAIL)
Completeness Assessment (scores for PRD, Architecture, Epics)
Alignment Assessment (PRD↔Architecture, Architecture↔Epics/Stories, cross-epic consistency)
Quality Assessment (story quality, dependencies, risks)
Gaps and Recommendations (critical/minor gaps, remediation)
Gate Decision with rationale
Next Steps

Example: E-commerce platform → CONCERNS ⚠️ due to missing security architecture and undefined payment gateway. Recommendation: Complete security section and add payment gateway ADR before proceeding.

Integration with Planning and Implementation

Planning → Solutioning Flow

Quick Flow:

Planning (tech-spec by PM)
  → Skip Solutioning
  → Phase 4 (Implementation)

BMad Method:

Planning (prd by PM - FRs/NFRs only)
  → Optional: create-ux-design (UX Designer)
  → architecture (Architect)
  → create-epics-and-stories (PM)
  → implementation-readiness (Architect)
  → Phase 4 (Implementation)

Enterprise:

Planning (prd by PM - FRs/NFRs only)
  → Optional: create-ux-design (UX Designer)
  → architecture (Architect)
  → Optional: security-architecture (Architect, future)
  → Optional: devops-strategy (Architect, future)
  → create-epics-and-stories (PM)
  → implementation-readiness (Architect)
  → Phase 4 (Implementation)

Note on TEA (Test Architect): TEA is fully operational with 8 workflows across all phases. TEA validates architecture testability during Phase 3 reviews but does not have a dedicated solutioning workflow. TEA's primary setup occurs in Phase 2 (*framework, *ci, *test-design) and testing execution in Phase 4 (*atdd, *automate, *test-review, *trace, *nfr-assess).

Note: Enterprise uses the same planning and architecture as BMad Method. The only difference is optional extended workflows added AFTER architecture but BEFORE create-epics-and-stories.

Solutioning → Implementation Handoff

Documents Produced:

architecture.md → Guides all dev agents during implementation
ADRs (in architecture) → Referenced by agents for technical decisions
Epic files (from create-epics-and-stories) → Work breakdown into implementable units
implementation-readiness.md → Confirms readiness for Phase 4

How Implementation Uses Solutioning:

sprint-planning - Loads architecture and epic files for sprint organization
dev-story - References architecture decisions and ADRs
code-review - Validates code follows architectural standards

Best Practices

1. Make Decisions Explicit

Don't leave technology choices implicit. Document decisions with rationale in ADRs so agents understand context.

2. Focus on Agent Conflicts

Architecture's primary job is preventing conflicting implementations. Focus on cross-cutting concerns.

3. Use ADRs for Key Decisions

Every significant technology choice should have an ADR explaining "why", not just "what".

4. Keep It Practical

Don't over-architect simple projects. BMad Simple projects need simple architecture.

5. Run Gate Check Before Implementation

Catching alignment issues in solutioning is 10× faster than discovering them mid-implementation.

6. Iterate Architecture

Architecture documents are living. Update them as you learn during implementation.

Decision Guide

Quick Flow

Planning: tech-spec (PM)
Solutioning: Skip entirely
Implementation: sprint-planning → dev-story

BMad Method

Planning: prd (PM) - creates FRs/NFRs only, NOT epics
Solutioning: Optional UX → architecture (Architect) → create-epics-and-stories (PM) → implementation-readiness (Architect)
Implementation: sprint-planning → epic-tech-context → dev-story

Enterprise

Planning: prd (PM) - creates FRs/NFRs only (same as BMad Method)
Solutioning: Optional UX → architecture (Architect) → Optional extended workflows (security-architecture, devops-strategy) → create-epics-and-stories (PM) → implementation-readiness (Architect)
Implementation: sprint-planning → epic-tech-context → dev-story

Key Difference: Enterprise adds optional extended workflows AFTER architecture but BEFORE create-epics-and-stories. Everything else is identical to BMad Method.

Note: TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See Test Architecture Guide for TEA's full lifecycle integration.

Common Anti-Patterns

❌ Skipping Architecture for Complex Projects

"Architecture slows us down, let's just start coding." Result: Agent conflicts, inconsistent design, massive rework

❌ Over-Engineering Simple Projects

"Let me design this simple feature like a distributed system." Result: Wasted time, over-engineering, analysis paralysis

❌ Template-Driven Architecture

"Fill out every section of this architecture template." Result: Documentation theater, no real decisions made

❌ Skipping Gate Check

"PRD and architecture look good enough, let's start." Result: Gaps discovered mid-sprint, wasted implementation time

✅ Correct Approach

Use architecture for BMad Method and Enterprise (both required)
Focus on decisions, not documentation volume
Enterprise: Add optional extended workflows (test/security/devops) after architecture
Always run gate check before implementation

Phase 2: Planning Workflows - Previous phase
Phase 4: Implementation Workflows - Next phase
Scale Adaptive System - Understanding tracks
Agents Guide - Complete agent reference

Troubleshooting

Q: Do I always need architecture? A: No. Quick Flow skips it. BMad Method and Enterprise both require it.

Q: How do I know if I need architecture? A: If you chose BMad Method or Enterprise track in planning (workflow-init), you need architecture to prevent agent conflicts.

Q: What's the difference between architecture and tech-spec? A: Tech-spec is implementation-focused for simple changes. Architecture is system design for complex multi-epic projects.

Q: Can I skip gate check? A: Only for Quick Flow. BMad Method and Enterprise both require gate check before Phase 4.

Q: What if gate check fails? A: Resolve the identified gaps (missing architecture sections, conflicting requirements) and re-run gate check.

Q: How long should architecture take? A: BMad Method: 1-2 days for architecture. Enterprise: 2-3 days total (1-2 days architecture + 0.5-1 day optional extended workflows). If taking longer, you may be over-documenting.

Q: Do ADRs need to be perfect? A: No. ADRs capture key decisions with rationale. They should be concise (1 page max per ADR).

Q: Can I update architecture during implementation? A: Yes! Architecture is living. Update it as you learn. Use correct-course workflow for significant changes.

Phase 3 Solutioning - Technical decisions before implementation.

20 KiB Raw Blame History Unescape Escape

BMM Solutioning Workflows (Phase 3)

Overview

Phase 3 Solutioning Workflow Map

Quick Reference

Why Solutioning Matters

The Problem Without Solutioning

The Solution With Solutioning

Solutioning vs Planning

Workflow Descriptions

architecture

create-epics-and-stories

implementation-readiness

Integration with Planning and Implementation

Planning → Solutioning Flow

Solutioning → Implementation Handoff

Best Practices

1. Make Decisions Explicit

2. Focus on Agent Conflicts

3. Use ADRs for Key Decisions

4. Keep It Practical

5. Run Gate Check Before Implementation

6. Iterate Architecture

Decision Guide

Quick Flow

BMad Method

Enterprise

Common Anti-Patterns

❌ Skipping Architecture for Complex Projects

❌ Over-Engineering Simple Projects

❌ Template-Driven Architecture

❌ Skipping Gate Check

✅ Correct Approach

Related Documentation

Troubleshooting

20 KiB

Raw Blame History