# BMM Solutioning Workflows (Phase 3)

## Overview

Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into **how** to build it (technical design). This phase is **required for Levels 3-4** and **optional for Level 2** projects.

**Key principle:** Prevent agent conflicts by making architectural decisions explicit and documented before implementation begins.

---

## Phase 3 Solutioning Flow

```mermaid
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
graph TB
    FromPRD["<b>FROM Phase 2</b><br/>PRD/GDD/Narrative/UX complete"]

    subgraph Solutioning["<b>PHASE 3: SOLUTIONING</b>"]
        direction TB
        Architecture["<b>Architect: architecture</b><br/>Technical design and decisions"]
        GateCheck["<b>Architect: solutioning-gate-check</b><br/>Validation before implementation"]
    end

    subgraph Optional["<b>OPTIONAL PATHS</b>"]
        direction LR
        Level2Skip["<b>Level 2:</b><br/>Skip if straightforward"]
    end

    FromPRD --> Architecture
    Architecture --> GateCheck
    GateCheck -->|PASS| Phase4["<b>Phase 4: Implementation</b>"]
    GateCheck -->|CONCERNS/FAIL| Architecture
    FromPRD -.->|Level 2 only| Level2Skip
    Level2Skip -.-> Phase4

    style FromPRD fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px,color:#000
    style Solutioning fill:#90caf9,stroke:#0d47a1,stroke-width:3px,color:#000
    style Optional fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
    style Phase4 fill:#ffcc80,stroke:#e65100,stroke-width:2px,color:#000

    style Architecture fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000
    style GateCheck fill:#64b5f6,stroke:#0d47a1,stroke-width:2px,color:#000
    style Level2Skip fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000
```

---

## Quick Reference

| Workflow                   | Project Levels | Purpose                                     |
| -------------------------- | -------------- | ------------------------------------------- |
| **architecture**           | 2-4            | Technical architecture and design decisions |
| **solutioning-gate-check** | 3-4            | Validate planning/solutioning completeness  |

**When to Skip Solutioning:**

- **Level 0-1**: Simple changes don't need architecture → Skip to Phase 4 (Implementation)
- **Level 2**: Optional - use if technically complex, skip if straightforward

**When Solutioning is Required:**

- **Level 3-4**: Multi-epic, multi-agent projects → Architecture prevents conflicts

---

## Understanding the Solutioning Phase

### Why Solutioning Matters

**Problem Without Solutioning:**

1. DEV agent implements Epic 1 using REST API
2. DEV agent implements Epic 2 using GraphQL
3. **Conflict**: Inconsistent API design, integration nightmare

**Solution With Solutioning:**

1. **architecture** workflow decides: "Use GraphQL for all APIs"
2. All DEV agents follow architecture decisions
3. **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    |

### Scale-Adaptive Solutioning

**Level 0-1 (Skip Solutioning):**

- Planning: Quick Spec (tech-spec workflow)
- Solutioning: **None**
- Implementation: dev-story directly

**Level 2 (Optional Solutioning):**

- Planning: Lightweight PRD
- Solutioning: **Optional** architecture
- Implementation: dev-story with or without architecture

**Level 3-4 (Required Solutioning):**

- Planning: Standard/Comprehensive PRD
- Solutioning: **Required** architecture + epic-tech-context
- Gate Check: **Required** solutioning-gate-check
- Implementation: dev-story guided by architecture

---

## architecture

### Purpose

Collaborative architectural decision facilitation that produces a decision-focused architecture document optimized for preventing agent conflicts. Replaces template-driven architecture with intelligent, adaptive conversation.

**Agent:** Architect
**Phase:** 3 (Solutioning)
**Project Levels:** 2-4
**Required:** Level 3-4, Optional Level 2

### When to Use

- Multi-epic projects (Level 3-4)
- Cross-cutting technical concerns
- Multiple agents will implement different parts
- Integration complexity exists
- Technology choices need alignment

**When to Skip:**

- Level 0-1 (simple changes)
- Level 2 with straightforward tech stack
- Single epic with clear technical approach

### Adaptive Conversation Approach

**This is NOT a template filler.** The architecture workflow:

1. **Discovers** your 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

### Process Overview

**Phase 1: Context Discovery (Steps 1-3)**

- Load PRD/GDD for requirements
- Understand project level and complexity
- Identify technical constraints
- Determine existing architecture (if brownfield)

**Phase 2: Architecture Definition (Steps 4-10)**

- System architecture (monolith, microservices, etc.)
- Data architecture (database, state management)
- API design (REST, GraphQL, gRPC)
- Frontend architecture (if applicable)
- Integration patterns
- Security architecture
- Deployment architecture

**Phase 3: Decision Documentation (Steps 11-13)**

- Architecture Decision Records (ADRs)
- Trade-off analysis
- Technology selections with rationale
- Non-negotiable standards

**Phase 4: Implementation Guidance (Step 14)**

- Epic-specific technical notes
- Directory structure
- Coding standards
- Testing strategy

### Inputs

Required:

- **PRD.md** or **GDD.md** (from Phase 2)
- **epics.md** (epic breakdown)

Optional:

- Existing architecture documentation (brownfield)
- Technical constraints document
- Infrastructure requirements
- Security requirements

### Outputs

**Primary Output:** `architecture-{project-name}-{date}.md`

**Document Structure:**

**1. Architecture Overview**

- System context
- Key principles
- Architectural style

**2. System Architecture**

- High-level system diagram
- Component interactions
- Communication patterns

**3. Data Architecture**

- Database design approach
- State management
- Caching strategy
- Data flow

**4. API Architecture**

- API style (REST/GraphQL/gRPC)
- Authentication/authorization
- Versioning strategy
- Error handling patterns

**5. Frontend Architecture** (if applicable)

- Framework selection
- State management
- Component architecture
- Routing approach

**6. Integration Architecture**

- Third-party integrations
- Message queuing
- Event-driven patterns
- API gateways

**7. Security Architecture**

- Authentication/authorization
- Data protection
- Security boundaries
- Compliance requirements

**8. Deployment Architecture**

- Deployment model
- CI/CD pipeline
- Environment strategy
- Monitoring and observability

**9. Architecture Decision Records (ADRs)**

- Key decisions with context
- Options considered
- Trade-off analysis
- Rationale for choices

**10. Epic-Specific Guidance**

- Technical notes per epic
- Implementation priorities
- Dependency sequencing

**11. Standards and Conventions**

- Directory structure
- Naming conventions
- Code organization
- Testing requirements

### Architecture Decision Records (ADRs)

**Purpose:** Document **why** decisions were made, not just what was decided.

**ADR Template:**

```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 API - Familiar, well-understood, but requires multiple endpoints
2. GraphQL - Flexible querying, single endpoint, learning curve
3. gRPC - High performance, but poor browser support

**Rationale:**

- PRD requires flexible data fetching (Epic 1, Epic 3)
- Mobile app needs bandwidth optimization (Epic 2)
- Team has GraphQL experience from previous project
- Allows frontend flexibility without backend changes

**Consequences:**

- Positive: Flexible querying, reduced API 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
- Epic 3: Admin Dashboard → Complex nested queries
```

### Example: Level 3 Architecture for E-Commerce Platform

**System Architecture:**

- Monolith (early stage, < 50K users)
- PostgreSQL database
- Redis for caching and sessions
- Next.js for frontend
- Deployed on Vercel + Railway

**Key ADRs:**

1. **ADR-001**: Use Next.js (vs React + Express)
   - Rationale: SEO critical, SSR needed, unified codebase
2. **ADR-002**: Use GraphQL (vs REST)
   - Rationale: Flexible querying for dashboard, mobile optimization
3. **ADR-003**: Use Stripe (vs PayPal + Stripe)
   - Rationale: Simpler integration, lower fees, better UX

**Epic Guidance:**

- **Epic 1 (Auth)**: NextAuth.js with PostgreSQL adapter
- **Epic 2 (Products)**: GraphQL with DataLoader for categories
- **Epic 3 (Cart)**: Redis for session-based cart (no DB writes)
- **Epic 4 (Checkout)**: Stripe webhooks for payment confirmation

**Standards:**

```
Directory Structure:
/pages          - Next.js routes
/components     - Reusable UI components
/lib            - Business logic
  /graphql      - GraphQL schema and resolvers
  /db           - Prisma models and migrations
  /services     - Third-party integrations
/tests          - Test files mirror /lib
```

### Related Workflows

- **prd/gdd** (Phase 2) - Requirements input
- **solutioning-gate-check** (Phase 3) - Validate completeness
- **tech-spec** (Phase 3) - Epic-level specifications (optional)
- **sprint-planning** (Phase 4) - Implementation tracking

---

## solutioning-gate-check

### Purpose

Systematically validate that all planning and solutioning phases are complete and properly aligned before transitioning to Phase 4 implementation. Ensures PRD, architecture, and stories are cohesive with no gaps or contradictions.

**Agent:** SM (Scrum Master)
**Phase:** 3 (Solutioning)
**Project Levels:** 3-4
**Required:** Level 3-4 only

### When to Use

**Always run before starting Phase 4** for Level 3-4 projects.

**Trigger Points:**

- After architecture workflow completes
- Before sprint-planning workflow
- When stakeholders request readiness check
- Before kicking off implementation

**Skip if:**

- Level 0-2 (no solutioning phase)
- Exploratory prototype (no formal planning)

### Purpose of Gate Check

**Prevents Common Issues:**

- ❌ Architecture doesn't address all epics
- ❌ Stories conflict with architecture decisions
- ❌ Requirements ambiguous or contradictory
- ❌ Missing critical dependencies
- ❌ Unclear success criteria

**Ensures:**

- ✅ PRD → Architecture → Stories alignment
- ✅ All epics have clear technical approach
- ✅ No contradictions or gaps
- ✅ Team ready to implement
- ✅ Stakeholders aligned

### Process Overview

**Phase 1: Document Loading (Step 1)**

- Load PRD/GDD
- Load architecture document
- Load epic files
- Load story files (if created)

**Phase 2: Completeness Check (Steps 2-4)**

- **PRD Completeness**: All required sections present
- **Architecture Completeness**: All technical areas addressed
- **Epic Completeness**: All epics from PRD have stories

**Phase 3: Alignment Check (Steps 5-7)**

- **PRD ↔ Architecture**: Architecture addresses all requirements
- **Architecture ↔ Epics**: Epics align with architecture decisions
- **Cross-Epic**: No contradictions between epics

**Phase 4: Quality Check (Steps 8-10)**

- **Acceptance Criteria**: All stories have clear AC
- **Dependencies**: Dependencies identified and sequenced
- **Risks**: High-risk items have mitigation plans

**Phase 5: Reporting (Step 11)**

- Generate gate check report
- List gaps and blockers
- Provide recommendations
- Issue PASS/CONCERNS/FAIL decision

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

**Quality Checks:**

- [ ] Acceptance criteria testable
- [ ] Stories appropriately sized (<5 days)
- [ ] High-risk items have mitigation
- [ ] Success metrics measurable

### Gate Decision Logic

**PASS** ✅

- All critical criteria met (PRD, Architecture, Epic completeness)
- Minor gaps acceptable with documented plan
- **Action**: Proceed to Phase 4 (Implementation)

**CONCERNS** ⚠️

- Some criteria not met but not blockers
- Gaps identified with clear resolution path
- Risks documented with mitigation
- **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

### Inputs

Required:

- PRD.md or GDD.md
- architecture.md
- epics.md
- Epic files (epic-1-_.md, epic-2-_.md, etc.)

Optional:

- Story files (if already created)
- Tech spec documents

### Outputs

**Primary Output:** `solutioning-gate-check-{date}.md`

**Document Structure:**

1. Executive Summary (PASS/CONCERNS/FAIL)
2. Completeness Assessment
   - PRD/GDD Score
   - Architecture Score
   - Epic/Story Score
3. Alignment Assessment
   - PRD ↔ Architecture alignment
   - Architecture ↔ Epic alignment
   - Cross-epic consistency
4. Quality Assessment
   - Story quality
   - Dependency clarity
   - Risk mitigation
5. Gaps and Recommendations
   - Critical gaps (blockers)
   - Minor gaps (address in parallel)
   - Recommendations for remediation
6. Gate Decision (PASS/CONCERNS/FAIL)
7. Next Steps

### Example: Gate Check for E-Commerce Platform

**Result:** CONCERNS ⚠️

**Completeness:**

- ✅ PRD complete (18/18 criteria)
- ⚠️ Architecture missing security section (15/18 criteria)
- ✅ Epics complete (24/24 criteria)

**Alignment:**

- ✅ PRD ↔ Architecture aligned
- ⚠️ Epic 4 (Checkout) has payment gateway undefined in architecture
- ✅ No cross-epic contradictions

**Quality:**

- ✅ Stories have acceptance criteria
- ⚠️ Epic 2, Story 3 is too large (10 day estimate)
- ✅ Dependencies identified

**Gaps Identified:**

1. **Critical**: Architecture missing security architecture section
   - **Impact**: Epic 1 (Auth) and Epic 4 (Checkout) lack security guidance
   - **Recommendation**: Complete security architecture

2. **High**: Payment gateway not selected
   - **Impact**: Epic 4 (Checkout) cannot proceed
   - **Recommendation**: Add ADR for payment gateway selection

3. **Medium**: Epic 2, Story 3 too large
   - **Impact**: Risk of story scope creep
   - **Recommendation**: Split into 2 stories

**Gate Decision:** CONCERNS ⚠️

- **Rationale**: Critical and high gaps block Epic 1 and Epic 4
- **Action**: Resolve gaps #1 and #2 before starting implementation

**Next Steps:**

1. Complete security architecture section
2. Document payment gateway ADR
3. Split Epic 2, Story 3
4. Re-run solutioning-gate-check
5. If PASS → Proceed to sprint-planning

### Related Workflows

- **architecture** (Phase 3) - Must complete before gate check
- **prd/gdd** (Phase 2) - Input to gate check
- **sprint-planning** (Phase 4) - Runs after PASS decision

---

## Integration with Phase 2 (Planning) and Phase 4 (Implementation)

### Planning → Solutioning Flow

**Level 0-1:**

```
Planning (tech-spec Quick Spec)
  → Skip Solutioning
  → Implementation (dev-story)
```

**Level 2:**

```
Planning (prd Lightweight)
  → Optional: architecture (if complex)
  → Implementation (sprint-planning → dev-story)
```

**Level 3-4:**

```
Planning (prd Standard/Comprehensive)
  → architecture (Required)
  → solutioning-gate-check (Required)
  → Implementation (sprint-planning → dev-story)
```

### Solutioning → Implementation Handoff

**Documents Produced:**

1. `architecture.md` → Guides all dev-story workflows
2. `ADRs` (in architecture) → Referenced by agents during implementation
3. `solutioning-gate-check.md` → Confirms readiness

**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 for Phase 3

### 1. Make Decisions Explicit

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

### 2. Focus on Agent Conflicts

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

### 3. Use ADRs for Key Decisions

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

### 4. Keep It Practical

Don't over-architect Level 2 projects. 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.

---

## Common Anti-Patterns

### ❌ Skipping Architecture for Level 3-4

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

### ❌ Over-Architecting Level 2

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

### ❌ 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 Level 3-4 (required)
- Keep Level 2 architecture simple (if used)
- Focus on decisions, not documentation volume
- Always run gate check before implementation

---

## Decision Guide: When to Use Solutioning Workflows

### Level 0-1 Projects

- **Planning**: tech-spec (Quick Spec)
- **Solutioning**: **Skip entirely**
- **Implementation**: dev-story directly

### Level 2 Projects (Simple)

- **Planning**: prd (Lightweight)
- **Solutioning**: **Skip** if straightforward tech
- **Implementation**: sprint-planning → dev-story

### Level 2 Projects (Technically Complex)

- **Planning**: prd (Lightweight)
- **Solutioning**: architecture (simplified)
- **Gate Check**: Optional
- **Implementation**: sprint-planning → dev-story

### Level 3-4 Projects

- **Planning**: prd/gdd (Standard/Comprehensive)
- **Solutioning**: architecture (comprehensive) → **Required**
- **Gate Check**: solutioning-gate-check → **Required**
- **Implementation**: sprint-planning → epic-tech-context → dev-story

---

## Summary

Phase 3 Solutioning workflows bridge planning and implementation:

| Workflow                   | Purpose                               | When Required                            |
| -------------------------- | ------------------------------------- | ---------------------------------------- |
| **architecture**           | Make technical decisions explicit     | Level 3-4 (required), Level 2 (optional) |
| **solutioning-gate-check** | Validate readiness for implementation | Level 3-4 only                           |

**Key Takeaway:** Solutioning prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.

**Next Phase:** Implementation (Phase 4) - Sprint-based story development

See: [workflows-implementation.md](./workflows-implementation.md)