BMAD-METHOD/src/modules/bmm/docs/workflows-solutioning.md

# 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

```mermaid
%%{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
            TestArch["<b>TEA: test-architecture</b><br/>(Future)"]
            SecArch["<b>Architect: security-architecture</b>"]
            DevOps["<b>Architect: devops-strategy</b>"]
        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 TestArch fill:#ef9a9a,stroke:#c62828,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:

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

**Key Outputs:**

**architecture.md** containing:

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

**ADR Format (Brief):**

```markdown
## 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:

1. Executive Summary (PASS/CONCERNS/FAIL)
2. Completeness Assessment (scores for PRD, Architecture, Epics)
3. Alignment Assessment (PRD↔Architecture, Architecture↔Epics, cross-epic consistency)
4. Quality Assessment (story quality, dependencies, risks)
5. Gaps and Recommendations (critical/minor gaps, remediation)
6. Gate Decision with rationale
7. 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: test-architecture (TEA, future)
  → Optional: security-architecture (Architect)
  → Optional: devops-strategy (Architect)
  → solutioning-gate-check (Architect)
  → Phase 4 (Implementation)
```

**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:**

1. **architecture.md** → Guides all dev agents during implementation
2. **ADRs** (in architecture) → Referenced by agents for technical decisions
3. **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 (test-architecture, 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.

---

## 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

---

## Related Documentation

- [Phase 2: Planning Workflows](./workflows-planning.md) - Previous phase
- [Phase 4: Implementation Workflows](./workflows-implementation.md) - Next phase
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding tracks
- [Agents Guide](./agents-guide.md) - 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._