Archon/bmad/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 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.

Quick Reference

Workflow	Project Levels	Duration	Purpose
architecture	2-4	2-6 hours	Technical architecture and design decisions
solutioning-gate-check	3-4	15-30 min	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 Typical Duration:

• Level 2: 1-2 hours (Simple architecture)
• Level 3: 2-4 hours (Standard architecture)
• Level 4: 4-8 hours (Complex architecture with ADRs)

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:

## 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 Typical Duration: 15-30 minutes

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 hours)

2. High: Payment gateway not selected

   • Impact: Epic 4 (Checkout) cannot proceed
   • Recommendation: Add ADR for payment gateway selection (1 hour)

3. Medium: Epic 2, Story 3 too large

   • Impact: Risk of story scope creep
   • Recommendation: Split into 2 stories (30 min)

Gate Decision: CONCERNS ⚠️

• Rationale: Critical and high gaps block Epic 1 and Epic 4
• Action: Resolve gaps #1 and #2 before starting implementation
• Timeline: Address in 3 hours, then re-run gate check

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