mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
More document Updtes and diagram improvements
This commit is contained in:
Brian Madison
@@ -1,83 +1,120 @@
|
||||
# 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.
|
||||
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:** Prevent agent conflicts by making architectural decisions explicit and documented 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 Flow
|
||||
## Phase 3 Solutioning Workflow Map
|
||||
|
||||
```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"]
|
||||
FromPlanning["<b>FROM Phase 2 Planning</b><br/>PRD/GDD/Tech-Spec complete"]
|
||||
|
||||
subgraph Solutioning["<b>PHASE 3: SOLUTIONING</b>"]
|
||||
subgraph QuickFlow["<b>QUICK FLOW PATH</b>"]
|
||||
direction TB
|
||||
Architecture["<b>Architect: architecture</b><br/>Technical design and decisions"]
|
||||
GateCheck["<b>Architect: solutioning-gate-check</b><br/>Validation before implementation"]
|
||||
SkipArch["<b>Skip Phase 3</b><br/>Go directly to Implementation"]
|
||||
end
|
||||
|
||||
subgraph Optional["<b>OPTIONAL PATHS</b>"]
|
||||
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
|
||||
Level2Skip["<b>Level 2:</b><br/>Skip if straightforward"]
|
||||
Pass["✅ PASS<br/>Proceed to Phase 4"]
|
||||
Concerns["⚠️ CONCERNS<br/>Proceed with caution"]
|
||||
Fail["❌ FAIL<br/>Resolve issues first"]
|
||||
end
|
||||
|
||||
FromPRD --> Architecture
|
||||
Architecture --> GateCheck
|
||||
GateCheck -->|PASS| Phase4["<b>Phase 4: Implementation</b>"]
|
||||
GateCheck -->|CONCERNS/FAIL| Architecture
|
||||
FromPRD -.->|Level 2 only| Level2Skip
|
||||
Level2Skip -.-> Phase4
|
||||
FromPlanning -->|Quick Flow| QuickFlow
|
||||
FromPlanning -->|BMad Method<br/>or Enterprise| Architecture
|
||||
|
||||
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
|
||||
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 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
|
||||
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 | Project Levels | Purpose |
|
||||
| -------------------------- | -------------- | ------------------------------------------- |
|
||||
| **architecture** | 2-4 | Technical architecture and design decisions |
|
||||
| **solutioning-gate-check** | 3-4 | Validate planning/solutioning completeness |
|
||||
| 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:**
|
||||
|
||||
- **Level 0-1**: Simple changes don't need architecture → Skip to Phase 4 (Implementation)
|
||||
- **Level 2**: Optional - use if technically complex, skip if straightforward
|
||||
- **Quick Flow:** Simple changes don't need architecture → Skip to Phase 4
|
||||
|
||||
**When Solutioning is Required:**
|
||||
|
||||
- **Level 3-4**: Multi-epic, multi-agent projects → Architecture prevents conflicts
|
||||
- **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
|
||||
|
||||
---
|
||||
|
||||
## Understanding the Solutioning Phase
|
||||
## Why Solutioning Matters
|
||||
|
||||
### Why Solutioning Matters
|
||||
### The Problem Without Solutioning
|
||||
|
||||
**Problem Without Solutioning:**
|
||||
```
|
||||
Agent 1 implements Epic 1 using REST API
|
||||
Agent 2 implements Epic 2 using GraphQL
|
||||
Result: Inconsistent API design, integration nightmare
|
||||
```
|
||||
|
||||
1. DEV agent implements Epic 1 using REST API
|
||||
2. DEV agent implements Epic 2 using GraphQL
|
||||
3. **Conflict**: Inconsistent API design, integration nightmare
|
||||
### The Solution With Solutioning
|
||||
|
||||
**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
|
||||
```
|
||||
architecture workflow decides: "Use GraphQL for all APIs"
|
||||
All agents follow architecture decisions
|
||||
Result: Consistent implementation, no conflicts
|
||||
```
|
||||
|
||||
### Solutioning vs Planning
|
||||
|
||||
@@ -90,221 +127,81 @@ graph TB
|
||||
| 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
|
||||
## Workflow Descriptions
|
||||
|
||||
### Purpose
|
||||
### architecture
|
||||
|
||||
Collaborative architectural decision facilitation that produces a decision-focused architecture document optimized for preventing agent conflicts. Replaces template-driven architecture with intelligent, adaptive conversation.
|
||||
**Purpose:** Make technical decisions explicit to prevent agent conflicts. Produces decision-focused architecture document optimized for AI consistency.
|
||||
|
||||
**Agent:** Architect
|
||||
**Phase:** 3 (Solutioning)
|
||||
**Project Levels:** 2-4
|
||||
**Required:** Level 3-4, Optional Level 2
|
||||
|
||||
### When to Use
|
||||
**When to Use:**
|
||||
|
||||
- Multi-epic projects (Level 3-4)
|
||||
- Multi-epic projects (BMad Complex, Enterprise)
|
||||
- Cross-cutting technical concerns
|
||||
- Multiple agents will implement different parts
|
||||
- Multiple agents implementing different parts
|
||||
- Integration complexity exists
|
||||
- Technology choices need alignment
|
||||
|
||||
**When to Skip:**
|
||||
|
||||
- Level 0-1 (simple changes)
|
||||
- Level 2 with straightforward tech stack
|
||||
- Quick Flow (simple changes)
|
||||
- BMad Method Simple with straightforward tech stack
|
||||
- Single epic with clear technical approach
|
||||
|
||||
### Adaptive Conversation Approach
|
||||
**Adaptive Conversation Approach:**
|
||||
|
||||
**This is NOT a template filler.** The architecture workflow:
|
||||
This is NOT a template filler. The architecture workflow:
|
||||
|
||||
1. **Discovers** your technical needs through conversation
|
||||
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
|
||||
|
||||
### Process Overview
|
||||
**Key Outputs:**
|
||||
|
||||
**Phase 1: Context Discovery (Steps 1-3)**
|
||||
**architecture.md** containing:
|
||||
|
||||
- Load PRD/GDD for requirements
|
||||
- Understand project level and complexity
|
||||
- Identify technical constraints
|
||||
- Determine existing architecture (if brownfield)
|
||||
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
|
||||
|
||||
**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 Format (Brief):**
|
||||
|
||||
```markdown
|
||||
## ADR-001: Use GraphQL for All APIs
|
||||
|
||||
**Status:** Accepted
|
||||
**Date:** 2025-11-02
|
||||
**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
|
||||
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, Epic 3)
|
||||
- PRD requires flexible data fetching (Epic 1, 3)
|
||||
- Mobile app needs bandwidth optimization (Epic 2)
|
||||
- Team has GraphQL experience from previous project
|
||||
- Allows frontend flexibility without backend changes
|
||||
- Team has GraphQL experience
|
||||
|
||||
**Consequences:**
|
||||
|
||||
- Positive: Flexible querying, reduced API versioning
|
||||
- Positive: Flexible querying, reduced versioning
|
||||
- Negative: Caching complexity, N+1 query risk
|
||||
- Mitigation: Use DataLoader for batching
|
||||
|
||||
@@ -312,93 +209,40 @@ Optional:
|
||||
|
||||
- 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
|
||||
**Example:** E-commerce platform → Monolith + PostgreSQL + Redis + Next.js + GraphQL, with ADRs explaining each choice and epic-specific guidance.
|
||||
|
||||
**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
|
||||
**Integration:** Feeds into Phase 4 (Implementation). All dev agents reference architecture during implementation.
|
||||
|
||||
---
|
||||
|
||||
## solutioning-gate-check
|
||||
### solutioning-gate-check
|
||||
|
||||
### Purpose
|
||||
**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.
|
||||
|
||||
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:** Architect
|
||||
|
||||
**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:**
|
||||
**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
|
||||
- Before kicking off implementation
|
||||
|
||||
**Skip if:**
|
||||
**When to Skip:**
|
||||
|
||||
- Level 0-2 (no solutioning phase)
|
||||
- Exploratory prototype (no formal planning)
|
||||
- Quick Flow (no solutioning)
|
||||
- BMad Simple (no gate check required)
|
||||
|
||||
### Purpose of Gate Check
|
||||
**Purpose of Gate Check:**
|
||||
|
||||
**Prevents Common Issues:**
|
||||
**Prevents:**
|
||||
|
||||
- ❌ Architecture doesn't address all epics
|
||||
- ❌ Stories conflict with architecture decisions
|
||||
- ❌ Requirements ambiguous or contradictory
|
||||
- ❌ Missing critical dependencies
|
||||
- ❌ Unclear success criteria
|
||||
|
||||
**Ensures:**
|
||||
|
||||
@@ -406,268 +250,150 @@ Systematically validate that all planning and solutioning phases are complete an
|
||||
- ✅ 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
|
||||
**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
|
||||
- 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
|
||||
- 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
|
||||
- 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
|
||||
- Architecture addresses all PRD requirements
|
||||
- Stories align with architecture decisions
|
||||
- No contradictions between epics
|
||||
- NFRs have technical approach
|
||||
- Integration points clear
|
||||
|
||||
**Quality Checks:**
|
||||
**Gate Decision Logic:**
|
||||
|
||||
- [ ] Acceptance criteria testable
|
||||
- [ ] Stories appropriately sized (<5 days)
|
||||
- [ ] High-risk items have mitigation
|
||||
- [ ] Success metrics measurable
|
||||
**✅ PASS**
|
||||
|
||||
### Gate Decision Logic
|
||||
|
||||
**PASS** ✅
|
||||
|
||||
- All critical criteria met (PRD, Architecture, Epic completeness)
|
||||
- All critical criteria met
|
||||
- Minor gaps acceptable with documented plan
|
||||
- **Action**: Proceed to Phase 4 (Implementation)
|
||||
- **Action:** Proceed to Phase 4
|
||||
|
||||
**CONCERNS** ⚠️
|
||||
**⚠️ 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
|
||||
- **Action:** Proceed with caution, address gaps in parallel
|
||||
|
||||
**FAIL** ❌
|
||||
**❌ FAIL**
|
||||
|
||||
- Critical gaps or contradictions
|
||||
- Architecture missing key decisions
|
||||
- Stories conflict with PRD/architecture
|
||||
- **Action**: BLOCK Phase 4, resolve issues first
|
||||
- **Action:** BLOCK Phase 4, resolve issues first
|
||||
|
||||
### Inputs
|
||||
**Key Outputs:**
|
||||
|
||||
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:**
|
||||
**solutioning-gate-check.md** containing:
|
||||
|
||||
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)
|
||||
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: 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
|
||||
**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 Phase 2 (Planning) and Phase 4 (Implementation)
|
||||
## Integration with Planning and Implementation
|
||||
|
||||
### Planning → Solutioning Flow
|
||||
|
||||
**Level 0-1:**
|
||||
**Quick Flow:**
|
||||
|
||||
```
|
||||
Planning (tech-spec Quick Spec)
|
||||
Planning (tech-spec by PM)
|
||||
→ Skip Solutioning
|
||||
→ Implementation (dev-story)
|
||||
→ Phase 4 (Implementation)
|
||||
```
|
||||
|
||||
**Level 2:**
|
||||
**BMad Method:**
|
||||
|
||||
```
|
||||
Planning (prd Lightweight)
|
||||
→ Optional: architecture (if complex)
|
||||
→ Implementation (sprint-planning → dev-story)
|
||||
Planning (prd by PM)
|
||||
→ architecture (Architect)
|
||||
→ solutioning-gate-check (Architect)
|
||||
→ Phase 4 (Implementation)
|
||||
```
|
||||
|
||||
**Level 3-4:**
|
||||
**Enterprise:**
|
||||
|
||||
```
|
||||
Planning (prd Standard/Comprehensive)
|
||||
→ architecture (Required)
|
||||
→ solutioning-gate-check (Required)
|
||||
→ Implementation (sprint-planning → dev-story)
|
||||
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-story workflows
|
||||
2. `ADRs` (in architecture) → Referenced by agents during implementation
|
||||
3. `solutioning-gate-check.md` → Confirms readiness
|
||||
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
|
||||
- **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
|
||||
## Best Practices
|
||||
|
||||
### 1. Make Decisions Explicit
|
||||
|
||||
Don't leave technology choices implicit. Document decisions with rationale so future agents understand context.
|
||||
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 by different agents. Focus on cross-cutting concerns.
|
||||
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 the "why", not just the "what".
|
||||
Every significant technology choice should have an ADR explaining "why", not just "what".
|
||||
|
||||
### 4. Keep It Practical
|
||||
|
||||
Don't over-architect Level 2 projects. Simple projects need simple architecture.
|
||||
Don't over-architect simple projects. BMad Simple projects need simple architecture.
|
||||
|
||||
### 5. Run Gate Check Before Implementation
|
||||
|
||||
@@ -679,78 +405,96 @@ Architecture documents are living. Update them as you learn during implementatio
|
||||
|
||||
---
|
||||
|
||||
## 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 Level 3-4
|
||||
### ❌ Skipping Architecture for Complex Projects
|
||||
|
||||
"Architecture slows us down, let's just start coding."
|
||||
→ **Result**: Agent conflicts, inconsistent design, rework
|
||||
**Result:** Agent conflicts, inconsistent design, massive rework
|
||||
|
||||
### ❌ Over-Architecting Level 2
|
||||
### ❌ Over-Engineering Simple Projects
|
||||
|
||||
"Let me design this simple feature like a distributed system."
|
||||
→ **Result**: Wasted time, over-engineering
|
||||
**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
|
||||
**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
|
||||
**Result:** Gaps discovered mid-sprint, wasted implementation time
|
||||
|
||||
### ✅ Correct Approach
|
||||
|
||||
- Use architecture for Level 3-4 (required)
|
||||
- Keep Level 2 architecture simple (if used)
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
## Decision Guide: When to Use Solutioning Workflows
|
||||
## Related Documentation
|
||||
|
||||
### 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
|
||||
- [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
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
## Troubleshooting
|
||||
|
||||
Phase 3 Solutioning workflows bridge planning and implementation:
|
||||
**Q: Do I always need architecture?**
|
||||
A: No. Quick Flow skips it. BMad Method and Enterprise both require it.
|
||||
|
||||
| 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 |
|
||||
**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.
|
||||
|
||||
**Key Takeaway:** Solutioning prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
|
||||
**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.
|
||||
|
||||
**Next Phase:** Implementation (Phase 4) - Sprint-based story development
|
||||
**Q: Can I skip gate check?**
|
||||
A: Only for Quick Flow. BMad Method and Enterprise both require gate check before Phase 4.
|
||||
|
||||
See: [workflows-implementation.md](./workflows-implementation.md)
|
||||
**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._
|
||||
|
||||
Reference in New Issue
Block a user