@zeyue0329/xiaoma-cli 1.0.48 → 6.0.0-alpha.13

package/src/modules/xmc/docs/workflows-solutioning.md

@@ -0,0 +1,509 @@
+# XMC Solutioning Workflows (Phase 3)
+
+## 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:** XiaoMa Method (complex projects), Enterprise Method
+
+**Optional for:** XiaoMa Method (simple projects), Quick Flow (skip entirely)
+
+---
+
+## Phase 3 Solutioning Workflow Overview
+
+Phase 3 Solutioning has different paths based on the planning track selected:
+
+### Quick Flow Path
+
+- From Planning: tech-spec complete
+- Action: Skip Phase 3 entirely
+- Next: Phase 4 (Implementation)
+
+### XiaoMa Method & Enterprise Path
+
+- From Planning: PRD with FRs/NFRs complete
+- Optional: create-ux-design (if UX is critical)
+- Required: architecture - System design with ADRs
+- Required: create-epics-and-stories - Break requirements into implementable stories
+- Required: implementation-readiness - Gate check validation
+- Enterprise additions: Optional security-architecture and devops-strategy (future workflows)
+
+### Gate Check Results
+
+- **PASS** - All criteria met, proceed to Phase 4
+- **CONCERNS** - Minor gaps identified, proceed with caution
+- **FAIL** - Critical issues, must resolve before Phase 4
+
+---
+
+## Quick Reference
+
+| Workflow                     | Agent       | Track                      | Purpose                                      |
+| ---------------------------- | ----------- | -------------------------- | -------------------------------------------- |
+| **create-ux-design**         | UX Designer | XiaoMa Method, Enterprise  | Optional UX design (after PRD, before arch)  |
+| **architecture**             | Architect   | XiaoMa Method, Enterprise  | Technical architecture and design decisions  |
+| **create-epics-and-stories** | PM          | XiaoMa Method, Enterprise  | Break FRs/NFRs into epics after architecture |
+| **implementation-readiness** | Architect   | XiaoMa 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:**
+
+- **XiaoMa Method:** Multi-epic projects need architecture to prevent conflicts
+- **Enterprise:** Same as XiaoMa 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? Then What units of work?     |
+| Output   | FRs/NFRs (Requirements) | Architecture + Epics/Stories      |
+| Agent    | PM                      | Architect → PM                    |
+| Audience | Stakeholders            | Developers                        |
+| Document | PRD (FRs/NFRs)          | Architecture + Epic Files         |
+| Level    | Business logic          | Technical design + Work breakdown |
+
+---
+
+## 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 (XiaoMa 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)
+- XiaoMa 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. **FR/NFR-Specific Guidance** - Technical approach per functional requirement, 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 FRs:**
+
+- FR-001: User Management → GraphQL mutations
+- FR-002: Mobile App → Optimized queries
+```
+
+**Example:** E-commerce platform → Monolith + PostgreSQL + Redis + Next.js + GraphQL, with ADRs explaining each choice and FR/NFR-specific guidance.
+
+**Integration:** Feeds into create-epics-and-stories workflow. Architecture provides the technical context needed for breaking FRs/NFRs into implementable epics and stories. All dev agents reference architecture during Phase 4 implementation.
+
+---
+
+### create-epics-and-stories
+
+**Purpose:** Transform PRD's functional and non-functional requirements into bite-sized stories organized into deliverable functional epics. This workflow runs AFTER architecture so epics/stories are informed by technical decisions.
+
+**Agent:** PM (Product Manager)
+
+**When to Use:**
+
+- After architecture workflow completes
+- When PRD contains FRs/NFRs ready for implementation breakdown
+- Before implementation-readiness gate check
+
+**Key Inputs:**
+
+- PRD (FRs/NFRs) from Phase 2 Planning
+- architecture.md with ADRs and technical decisions
+- Optional: UX design artifacts
+
+**Why After Architecture:**
+
+The create-epics-and-stories workflow runs AFTER architecture because:
+
+1. **Informed Story Sizing:** Architecture decisions (database choice, API style, etc.) affect story complexity
+2. **Dependency Awareness:** Architecture reveals technical dependencies between stories
+3. **Technical Feasibility:** Stories can be properly scoped knowing the tech stack
+4. **Consistency:** All stories align with documented architectural patterns
+
+**Key Outputs:**
+
+Epic files (one per epic) containing:
+
+1. Epic objective and scope
+2. User stories with acceptance criteria
+3. Story priorities (P0/P1/P2/P3)
+4. Dependencies between stories
+5. Technical notes referencing architecture decisions
+
+**Example:** E-commerce PRD with FR-001 (User Registration), FR-002 (Product Catalog) → Epic 1: User Management (3 stories), Epic 2: Product Display (4 stories), each story referencing relevant ADRs.
+
+---
+
+### implementation-readiness
+
+**Purpose:** Systematically validate that planning and solutioning are complete and aligned before Phase 4 implementation. Ensures PRD, architecture, and epics are cohesive with no gaps.
+
+**Agent:** Architect
+
+**When to Use:**
+
+- **Always** before Phase 4 for XiaoMa Complex and Enterprise projects
+- After create-epics-and-stories workflow completes
+- Before sprint-planning workflow
+- When stakeholders request readiness check
+
+**When to Skip:**
+
+- Quick Flow (no solutioning)
+- XiaoMa Simple (no gate check required)
+
+**Purpose of Gate Check:**
+
+**Prevents:**
+
+- ❌ Architecture doesn't address all FRs/NFRs
+- ❌ Epics conflict with architecture decisions
+- ❌ Requirements ambiguous or contradictory
+- ❌ Missing critical dependencies
+
+**Ensures:**
+
+- ✅ PRD → Architecture → Epics 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
+- Functional requirements (FRs) complete
+- 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
+- FR/NFR-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 FRs/NFRs
+- Epics 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
+- Epics conflict with PRD/architecture
+- **Action:** BLOCK Phase 4, resolve issues first
+
+**Key Outputs:**
+
+**implementation-readiness.md** containing:
+
+1. Executive Summary (PASS/CONCERNS/FAIL)
+2. Completeness Assessment (scores for PRD, Architecture, Epics)
+3. Alignment Assessment (PRD↔Architecture, Architecture↔Epics/Stories, 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)
+```
+
+**XiaoMa Method:**
+
+```
+Planning (prd by PM - FRs/NFRs only)
+  → Optional: create-ux-design (UX Designer)
+  → architecture (Architect)
+  → create-epics-and-stories (PM)
+  → implementation-readiness (Architect)
+  → Phase 4 (Implementation)
+```
+
+**Enterprise:**
+
+```
+Planning (prd by PM - FRs/NFRs only)
+  → Optional: create-ux-design (UX Designer)
+  → architecture (Architect)
+  → Optional: security-architecture (Architect, future)
+  → Optional: devops-strategy (Architect, future)
+  → create-epics-and-stories (PM)
+  → implementation-readiness (Architect)
+  → Phase 4 (Implementation)
+```
+
+**Note on TEA (Test Architect):** TEA is fully operational with 8 workflows across all phases. TEA validates architecture testability during Phase 3 reviews but does not have a dedicated solutioning workflow. TEA's primary setup occurs in Phase 2 (`*framework`, `*ci`, `*test-design`) and testing execution in Phase 4 (`*atdd`, `*automate`, `*test-review`, `*trace`, `*nfr-assess`).
+
+**Note:** Enterprise uses the same planning and architecture as XiaoMa Method. The only difference is optional extended workflows added AFTER architecture but BEFORE create-epics-and-stories.
+
+### 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. **Epic files** (from create-epics-and-stories) → Work breakdown into implementable units
+4. **implementation-readiness.md** → Confirms readiness for Phase 4
+
+**How Implementation Uses Solutioning:**
+
+- **sprint-planning** - Loads architecture and epic files for sprint organization
+- **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. XiaoMa 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
+
+### XiaoMa Method
+
+- **Planning:** prd (PM) - creates FRs/NFRs only, NOT epics
+- **Solutioning:** Optional UX → architecture (Architect) → create-epics-and-stories (PM) → implementation-readiness (Architect)
+- **Implementation:** sprint-planning → create-story → dev-story
+
+### Enterprise
+
+- **Planning:** prd (PM) - creates FRs/NFRs only (same as XiaoMa Method)
+- **Solutioning:** Optional UX → architecture (Architect) → Optional extended workflows (security-architecture, devops-strategy) → create-epics-and-stories (PM) → implementation-readiness (Architect)
+- **Implementation:** sprint-planning → create-story → dev-story
+
+**Key Difference:** Enterprise adds optional extended workflows AFTER architecture but BEFORE create-epics-and-stories. Everything else is identical to XiaoMa Method.
+
+**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](test-architecture.md) for TEA's full lifecycle integration.
+
+---
+
+## Common Anti-Patterns
+
+### ❌ Skipping Architecture for Complex Projects
+
+"Architecture slows us down, let's just start coding."
+**Result:** Agent conflicts, inconsistent design, massive rework
+
+### ❌ Over-Engineering Simple Projects
+
+"Let me design this simple feature like a distributed system."
+**Result:** Wasted time, over-engineering, analysis paralysis
+
+### ❌ Template-Driven Architecture
+
+"Fill out every section of this architecture template."
+**Result:** Documentation theater, no real decisions made
+
+### ❌ Skipping Gate Check
+
+"PRD and architecture look good enough, let's start."
+**Result:** Gaps discovered mid-sprint, wasted implementation time
+
+### ✅ Correct Approach
+
+- Use architecture for XiaoMa 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. XiaoMa Method and Enterprise both require it.
+
+**Q: How do I know if I need architecture?**
+A: If you chose XiaoMa 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. XiaoMa 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: XiaoMa 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._