17 KiB

Raw Permalink 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/GDD/Tech-Spec 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
        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

        GateCheck["<b>Architect: solutioning-gate-check</b><br/>Validation before Phase 4"]

        Architecture -.->|Enterprise only| Optional
        Architecture --> GateCheck
        Optional -.-> 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| Architecture

    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 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 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
architecture	Architect	BMad Method, Enterprise	Technical architecture and design decisions
solutioning-gate-check	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?
Output	Requirements	Technical Design
Agent	PM	Architect
Audience	Stakeholders	Developers
Document	PRD/GDD	Architecture + Tech Spec
Level	Business logic	Implementation detail

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
Epic-Specific Guidance - Technical notes per epic, 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 Epics:**

- Epic 1: User Management → GraphQL mutations
- Epic 2: Mobile App → Optimized queries

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

Integration: Feeds into Phase 4 (Implementation). All dev agents reference architecture during implementation.

solutioning-gate-check

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

Agent: Architect

When to Use:

Always before Phase 4 for BMad Complex and Enterprise projects
After architecture 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 epics
❌ Stories conflict with architecture decisions
❌ Requirements ambiguous or contradictory
❌ Missing critical dependencies

Ensures:

✅ PRD → Architecture → Stories 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
Feature requirements complete
All epics defined with objectives
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
Epic-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 requirements
Stories 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
Stories conflict with PRD/architecture
Action: BLOCK Phase 4, resolve issues first

Key Outputs:

solutioning-gate-check.md containing:

Executive Summary (PASS/CONCERNS/FAIL)
Completeness Assessment (scores for PRD, Architecture, Epics)
Alignment Assessment (PRD↔Architecture, Architecture↔Epics, 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)
  → architecture (Architect)
  → solutioning-gate-check (Architect)
  → Phase 4 (Implementation)

Enterprise:

Planning (prd by PM - same as BMad Method)
  → architecture (Architect)
  → Optional: security-architecture (Architect, future)
  → Optional: devops-strategy (Architect, future)
  → solutioning-gate-check (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 gate check.

Solutioning → Implementation Handoff

Documents Produced:

architecture.md → Guides all dev agents during implementation
ADRs (in architecture) → Referenced by agents for technical decisions
solutioning-gate-check.md → Confirms readiness for Phase 4

How Implementation Uses Solutioning:

sprint-planning - Loads architecture for epic sequencing
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)
Solutioning: architecture (Architect) → solutioning-gate-check (Architect)
Implementation: sprint-planning → epic-tech-context → dev-story

Enterprise

Planning: prd (PM) - same as BMad Method
Solutioning: architecture (Architect) → Optional extended workflows (security-architecture, devops-strategy) → solutioning-gate-check (Architect)
Implementation: sprint-planning → epic-tech-context → dev-story

Key Difference: Enterprise adds optional extended workflows AFTER architecture but BEFORE gate check. 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.

17 KiB Raw Permalink Blame History Unescape Escape