mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-17 09:45:25 +00:00
More document Updtes and diagram improvements
This commit is contained in:
Brian Madison
parent
412a7d1ed8
commit
6fa6ebab12
@ -52,7 +52,7 @@ Complete guide to BMM's AI agent team:
|
||||
- Example party compositions
|
||||
- Multi-module integration (BMM + CIS + BMB + custom)
|
||||
- Agent customization in party mode
|
||||
- Best practices and troubleshooting
|
||||
- Best practices
|
||||
|
||||
---
|
||||
|
||||
@ -65,7 +65,7 @@ Comprehensive guide for brownfield development:
|
||||
- Track selection for brownfield
|
||||
- Integration with existing patterns
|
||||
- Phase-by-phase workflow guidance
|
||||
- Common scenarios and troubleshooting
|
||||
- Common scenarios
|
||||
|
||||
---
|
||||
|
||||
@ -75,7 +75,6 @@ Essential reference materials:
|
||||
|
||||
- **[Glossary](./glossary.md)** - Key terminology and concepts
|
||||
- **[FAQ](./faq.md)** - Frequently asked questions across all topics
|
||||
- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
|
||||
- **[Enterprise Agentic Development](./enterprise-agentic-development.md)** - Team collaboration strategies
|
||||
|
||||
---
|
||||
@ -99,7 +98,7 @@ Essential reference materials:
|
||||
→ See [Scale Adaptive System](./scale-adaptive-system.md)
|
||||
|
||||
**Find specific commands or answers**
|
||||
→ Check [FAQ](./faq.md) or [Troubleshooting](./troubleshooting.md)
|
||||
→ Check [FAQ](./faq.md)
|
||||
|
||||
---
|
||||
|
||||
@ -213,12 +212,12 @@ flowchart TD
|
||||
SAS --> IMPL
|
||||
BF --> IMPL
|
||||
|
||||
IMPL --> REF[Quick References<br/>Glossary, FAQ, Troubleshooting]
|
||||
IMPL --> REF[Quick References<br/>Glossary, FAQ]
|
||||
|
||||
style START fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style QS fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style DECIDE fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style IMPL fill:#f9f,stroke:#333,stroke-width:2px
|
||||
style START fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
style QS fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||||
style DECIDE fill:#ffb,stroke:#333,stroke-width:2px,color:#000
|
||||
style IMPL fill:#f9f,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -1013,7 +1013,6 @@ Quick reference for agent selection:
|
||||
|
||||
- [Enterprise Agentic Development](./enterprise-agentic-development.md) - Team collaboration
|
||||
- [FAQ](./faq.md) - Common questions
|
||||
- [Troubleshooting](./troubleshooting.md) - Problem resolution
|
||||
- [Glossary](./glossary.md) - Terminology reference
|
||||
|
||||
---
|
||||
|
||||
@ -12,7 +12,6 @@
|
||||
|
||||
- [Quick Reference](#quick-reference) - Commands and files
|
||||
- [Common Scenarios](#common-scenarios) - Real-world examples
|
||||
- [Troubleshooting](#troubleshooting) - Problem solutions
|
||||
- [Best Practices](#best-practices) - Success tips
|
||||
|
||||
---
|
||||
@ -336,8 +335,8 @@ flowchart TD
|
||||
CHECK -->|Yes| CREATE
|
||||
CHECK -->|No| RETRO
|
||||
|
||||
style SPRINT fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style RETRO fill:#fbf,stroke:#333,stroke-width:2px
|
||||
style SPRINT fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
style RETRO fill:#fbf,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
**Status Progression:**
|
||||
@ -534,8 +533,6 @@ Document in tech-spec/architecture:
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
For complete troubleshooting, see [Troubleshooting Guide](./troubleshooting.md).
|
||||
|
||||
### AI Agents Lack Codebase Understanding
|
||||
|
||||
**Symptoms:**
|
||||
@ -706,9 +703,9 @@ flowchart TD
|
||||
PRD --> IMPL
|
||||
PRD2 --> IMPL
|
||||
|
||||
style START fill:#f9f,stroke:#333,stroke-width:2px
|
||||
style DOC fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style IMPL fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style START fill:#f9f,stroke:#333,stroke-width:2px,color:#000
|
||||
style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000
|
||||
style IMPL fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
@ -735,7 +732,6 @@ flowchart TD
|
||||
- **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
|
||||
- **[Glossary](./glossary.md)** - Key terminology
|
||||
- **[FAQ](./faq.md)** - Common questions
|
||||
- **[Troubleshooting](./troubleshooting.md)** - Problem resolution
|
||||
- **[Workflow Documentation](./README.md#-workflow-guides)** - Complete workflow reference
|
||||
|
||||
---
|
||||
|
||||
@ -557,11 +557,10 @@ Trust your expertise - BMM supports your decisions.
|
||||
|
||||
**A:**
|
||||
|
||||
1. Check [Troubleshooting Guide](./troubleshooting.md) for common issues
|
||||
2. Search [Complete Documentation](./README.md) for related topics
|
||||
3. Ask in [Discord Community](https://discord.gg/gk8jAdXWmj) (#general-dev)
|
||||
4. Open a [GitHub Issue](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
5. Watch [YouTube Tutorials](https://www.youtube.com/@BMadCode)
|
||||
1. Search [Complete Documentation](./README.md) for related topics
|
||||
2. Ask in [Discord Community](https://discord.gg/gk8jAdXWmj) (#general-dev)
|
||||
3. Open a [GitHub Issue](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
4. Watch [YouTube Tutorials](https://www.youtube.com/@BMadCode)
|
||||
|
||||
### Q: How do I report a bug or request a feature?
|
||||
|
||||
@ -580,7 +579,6 @@ Please include:
|
||||
|
||||
- [Quick Start Guide](./quick-start.md) - Get started with BMM
|
||||
- [Glossary](./glossary.md) - Terminology reference
|
||||
- [Troubleshooting](./troubleshooting.md) - Problem resolution
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels
|
||||
- [Brownfield Guide](./brownfield-guide.md) - Existing codebase workflows
|
||||
|
||||
|
||||
@ -318,4 +318,3 @@ Quick Spec Flow feature that automatically detects existing code style, naming c
|
||||
- [Brownfield Guide](./brownfield-guide.md) - Working with existing codebases
|
||||
- [Quick Spec Flow](./quick-spec-flow.md) - Fast-track for Quick Flow track
|
||||
- [FAQ](./faq.md) - Common questions
|
||||
- [Troubleshooting](./troubleshooting.md) - Problem resolution
|
||||
|
||||
@ -60,10 +60,10 @@ flowchart TD
|
||||
STORIES --> IMPL
|
||||
IMPL --> DONE
|
||||
|
||||
style START fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style IMPL fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style DONE fill:#f9f,stroke:#333,stroke-width:3px
|
||||
style START fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
style OPTIONAL fill:#ffb,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style IMPL fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||||
style DONE fill:#f9f,stroke:#333,stroke-width:3px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -323,10 +323,10 @@ flowchart LR
|
||||
P2 --> P3
|
||||
P3 --> P4
|
||||
|
||||
style P1 fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style P2 fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style P3 fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style P4 fill:#fbf,stroke:#333,stroke-width:2px
|
||||
style P1 fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||||
style P2 fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
style P3 fill:#ffb,stroke:#333,stroke-width:2px,color:#000
|
||||
style P4 fill:#fbf,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
## Common Questions
|
||||
|
||||
@ -51,9 +51,9 @@ flowchart TD
|
||||
Q1 -->|Yes| QF[Quick Flow<br/>Tech-spec only]
|
||||
Q1 -->|Uncertain| M
|
||||
|
||||
style QF fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style M fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style E fill:#f9f,stroke:#333,stroke-width:2px
|
||||
style QF fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
style M fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||||
style E fill:#f9f,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
### Quick Keywords
|
||||
@ -389,8 +389,8 @@ flowchart TD
|
||||
TRACK -->|Method| M[PRD + Arch]
|
||||
TRACK -->|Enterprise| E[PRD + Arch + Sec/Ops]
|
||||
|
||||
style DOC fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style TRACK fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000
|
||||
style TRACK fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -1,680 +0,0 @@
|
||||
# BMM Troubleshooting Guide
|
||||
|
||||
Common issues and solutions for the BMad Method Module.
|
||||
|
||||
---
|
||||
|
||||
## Quick Diagnosis
|
||||
|
||||
**Use this flowchart to find your issue:**
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START{What's the problem?}
|
||||
|
||||
START -->|Can't get started| SETUP[Setup & Installation Issues]
|
||||
START -->|Wrong level detected| LEVEL[Level Detection Problems]
|
||||
START -->|Workflow not working| WORKFLOW[Workflow Issues]
|
||||
START -->|Agent lacks context| CONTEXT[Context & Documentation Issues]
|
||||
START -->|Implementation problems| IMPL[Implementation Issues]
|
||||
START -->|Files/paths wrong| FILES[File & Path Issues]
|
||||
|
||||
style START fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style SETUP fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style LEVEL fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style WORKFLOW fill:#fbf,stroke:#333,stroke-width:2px
|
||||
style CONTEXT fill:#f9f,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Setup and Installation Issues](#setup-and-installation-issues)
|
||||
- [Level Detection Problems](#level-detection-problems)
|
||||
- [Workflow Issues](#workflow-issues)
|
||||
- [Context and Documentation Issues](#context-and-documentation-issues)
|
||||
- [Implementation Issues](#implementation-issues)
|
||||
- [File and Path Issues](#file-and-path-issues)
|
||||
- [Agent Behavior Issues](#agent-behavior-issues)
|
||||
- [Integration Issues (Brownfield)](#integration-issues-brownfield)
|
||||
|
||||
---
|
||||
|
||||
## Setup and Installation Issues
|
||||
|
||||
### Problem: BMM not found after installation
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- `bmad` command not recognized
|
||||
- Agent files not accessible
|
||||
- Workflows don't load
|
||||
|
||||
**Solution:**
|
||||
|
||||
```bash
|
||||
# Check if BMM is installed
|
||||
ls bmad/
|
||||
|
||||
# If not present, run installer
|
||||
npx bmad-method@alpha install
|
||||
|
||||
# For fresh install
|
||||
npx bmad-method@alpha install --skip-version-prompt
|
||||
```
|
||||
|
||||
### Problem: Agents don't have menu
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Load agent file but no menu appears
|
||||
- Agent doesn't respond to commands
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Ensure you're loading the correct agent file path: `bmad/bmm/agents/[agent-name].md`
|
||||
2. Wait a few seconds for agent to initialize
|
||||
3. Try asking "show menu" or "help"
|
||||
4. Check IDE supports Markdown rendering with context
|
||||
5. For Claude Code: Ensure agent file is open in chat context
|
||||
|
||||
### Problem: Workflows not found
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Agent says workflow doesn't exist
|
||||
- Menu shows workflow but won't run
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check workflow exists: `ls bmad/bmm/workflows/`
|
||||
2. Verify agent has access to workflow (check agent's workflow list)
|
||||
3. Try using menu number instead of workflow name
|
||||
4. Restart chat with agent in fresh session
|
||||
|
||||
---
|
||||
|
||||
## Level Detection Problems
|
||||
|
||||
### Problem: workflow-init suggests wrong level
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Detects Level 3 but you only need Level 1
|
||||
- Suggests Level 1 but project is actually Level 2
|
||||
- Can't figure out appropriate level
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Override the suggestion** - workflow-init always asks for confirmation, just say "no" and choose correct level
|
||||
2. **Be specific in description** - Use level keywords when describing:
|
||||
- "fix bug" → Level 0
|
||||
- "add small feature" → Level 1
|
||||
- "build dashboard" → Level 2
|
||||
3. **Manual override** - You can always switch levels later if needed
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
workflow-init: "Level 3 project?"
|
||||
You: "No, this is just adding OAuth login - Level 1"
|
||||
workflow-init: "Got it, creating Level 1 workflow"
|
||||
```
|
||||
|
||||
### Problem: Project level unclear
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Between Level 1 and Level 2
|
||||
- Not sure if architecture needed
|
||||
- Story count uncertain
|
||||
|
||||
**Solution:**
|
||||
**When in doubt, start smaller:**
|
||||
|
||||
- Choose Level 1 instead of Level 2
|
||||
- You can always run `create-prd` later if needed
|
||||
- Level 1 is faster, less overhead
|
||||
- Easy to upgrade, hard to downgrade
|
||||
|
||||
**Decision criteria:**
|
||||
|
||||
- Single epic with related stories? → Level 1
|
||||
- Multiple independent epics? → Level 2
|
||||
- Need product-level planning? → Level 2
|
||||
- Just need technical plan? → Level 1
|
||||
|
||||
### Problem: Old planning docs influencing level detection
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Old Level 3 PRD in folder
|
||||
- Working on new Level 0 bug fix
|
||||
- workflow-init suggests Level 3
|
||||
|
||||
**Solution:**
|
||||
workflow-init asks: "Is this work in progress or previous effort?"
|
||||
|
||||
- Answer: "Previous effort"
|
||||
- Then describe your NEW work clearly
|
||||
- System will detect level based on NEW work, not old artifacts
|
||||
|
||||
---
|
||||
|
||||
## Workflow Issues
|
||||
|
||||
### Problem: Workflow fails or hangs
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Workflow starts but doesn't complete
|
||||
- Agent stops responding mid-workflow
|
||||
- Progress stalls
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check context limits** - Start fresh chat for complex workflows
|
||||
2. **Verify prerequisites**:
|
||||
- Phase 2 needs Phase 1 complete (if used)
|
||||
- Phase 3 needs Phase 2 complete
|
||||
- Phase 4 needs Phase 3 complete (if Level 3-4)
|
||||
3. **Restart workflow** - Load agent in new chat and restart
|
||||
4. **Check status file** - Verify `bmm-workflow-status.md` or `sprint-status.yaml` is present and valid
|
||||
|
||||
### Problem: Agent says "workflow not found"
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Request workflow by name
|
||||
- Agent doesn't recognize it
|
||||
- Menu doesn't show workflow
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check spelling/format - Use exact workflow name or menu shortcut (*prd not *PRD)
|
||||
2. Verify agent has workflow:
|
||||
- PM agent: prd, tech-spec
|
||||
- Architect agent: create-architecture, validate-architecture
|
||||
- SM agent: sprint-planning, create-story, story-context
|
||||
3. Try menu number instead of name
|
||||
4. Check you're using correct agent for workflow
|
||||
|
||||
### Problem: Sprint-planning workflow fails
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Can't create sprint-status.yaml
|
||||
- Epics not extracted from files
|
||||
- Status file empty or incorrect
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Verify epic files exist**:
|
||||
- Level 1: tech-spec with epic
|
||||
- Level 2-4: epics.md or sharded epic files
|
||||
2. **Check file format**:
|
||||
- Epic files should be valid Markdown
|
||||
- Epic headers should be clear (## Epic Name)
|
||||
3. **Run in Phase 4 only** - Ensure Phase 2/3 complete first
|
||||
4. **Check file paths** - Epic files should be in correct output folder
|
||||
|
||||
### Problem: story-context generates empty or wrong context
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Context file created but has no useful content
|
||||
- Context doesn't reference existing code
|
||||
- Missing technical guidance
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Run epic-tech-context first** - story-context builds on epic context
|
||||
2. **Check story file exists** - Verify story was created by create-story
|
||||
3. **For brownfield**:
|
||||
- Ensure document-project was run
|
||||
- Verify docs/index.md exists with codebase context
|
||||
4. **Try regenerating** - Sometimes needs fresh attempt with more specific story details
|
||||
|
||||
---
|
||||
|
||||
## Context and Documentation Issues
|
||||
|
||||
### Problem: AI agents lack codebase understanding (Brownfield)
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Suggestions don't align with existing patterns
|
||||
- Ignores available components
|
||||
- Proposes approaches that conflict with architecture
|
||||
- Doesn't reference existing code
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Run document-project** - Critical for brownfield projects
|
||||
```
|
||||
Load Analyst agent → run document-project
|
||||
Choose scan level: Deep (recommended for PRD prep)
|
||||
```
|
||||
2. **Verify docs/index.md exists** - This is master entry point for AI agents
|
||||
3. **Check documentation completeness**:
|
||||
- Review generated docs/index.md
|
||||
- Ensure key systems are documented
|
||||
4. **Run deep-dive on specific areas** if needed
|
||||
|
||||
### Problem: Have documentation but agents can't find it
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- README.md, ARCHITECTURE.md exist
|
||||
- AI agents still ask questions answered in docs
|
||||
- No docs/index.md file
|
||||
|
||||
**Solution:**
|
||||
**Option 1: Quick fix (2-5min)**
|
||||
Run `index-docs` task:
|
||||
|
||||
- Located at `bmad/core/tasks/index-docs.xml`
|
||||
- Scans existing docs and generates index.md
|
||||
- Lightweight, just creates navigation
|
||||
|
||||
**Option 2: Comprehensive (10-30min)**
|
||||
Run document-project workflow:
|
||||
|
||||
- Discovers existing docs in Step 2
|
||||
- Generates NEW AI-friendly documentation from codebase
|
||||
- Creates index.md linking to BOTH existing and new docs
|
||||
|
||||
**Why this matters:** AI agents need structured entry point (index.md) to navigate docs efficiently.
|
||||
|
||||
### Problem: document-project takes too long
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Exhaustive scan running for hours
|
||||
- Impatient to start planning
|
||||
|
||||
**Solution:**
|
||||
**Choose appropriate scan level:**
|
||||
|
||||
- **Quick (2-5min)** - Pattern analysis, no source reading - Good for initial overview
|
||||
- **Deep (10-30min)** - Reads critical paths - **Recommended for most brownfield projects**
|
||||
- **Exhaustive (30-120min)** - Reads all files - Only for migration planning or complete understanding
|
||||
|
||||
For most brownfield projects, **Deep scan is sufficient**.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Issues
|
||||
|
||||
### Problem: Existing tests breaking (Brownfield)
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Regression test failures
|
||||
- Previously working functionality broken
|
||||
- Integration tests failing
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Review changes against existing patterns**:
|
||||
- Check if new code follows existing conventions
|
||||
- Verify API contracts unchanged (unless intentionally versioned)
|
||||
2. **Run test-review workflow** (TEA agent):
|
||||
- Analyzes test coverage
|
||||
- Identifies regression risks
|
||||
- Suggests fixes
|
||||
3. **Add regression testing to DoD**:
|
||||
- All existing tests must pass
|
||||
- Add integration tests for new code
|
||||
4. **Consider feature flags** for gradual rollout
|
||||
|
||||
### Problem: Story takes much longer than estimated
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Story estimated 4 hours, took 12 hours
|
||||
- Acceptance criteria harder than expected
|
||||
- Hidden complexity discovered
|
||||
|
||||
**Solution:**
|
||||
**This is normal!** Estimates are estimates. To handle:
|
||||
|
||||
1. **Continue until DoD met** - Don't compromise quality
|
||||
2. **Document learnings in retrospective**:
|
||||
- What caused the overrun?
|
||||
- What should we watch for next time?
|
||||
3. **Consider splitting story** if it's truly two stories
|
||||
4. **Adjust future estimates** based on this data
|
||||
|
||||
**Don't stress about estimate accuracy** - use them for learning, not judgment.
|
||||
|
||||
### Problem: Integration points unclear
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Not sure how to connect new code to existing
|
||||
- Unsure which files to modify
|
||||
- Multiple possible integration approaches
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **For brownfield**:
|
||||
- Ensure document-project captured existing architecture
|
||||
- Review architecture docs before implementing
|
||||
2. **Check story-context** - Should document integration points
|
||||
3. **In tech-spec/architecture** - Explicitly document:
|
||||
- Which existing modules to modify
|
||||
- What APIs/services to integrate with
|
||||
- Data flow between new and existing code
|
||||
4. **Run integration-planning workflow** (Level 3-4):
|
||||
- Architect agent creates integration strategy
|
||||
|
||||
### Problem: Inconsistent patterns being introduced
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- New code style doesn't match existing
|
||||
- Different architectural approach
|
||||
- Not following team conventions
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check convention detection** (Quick Spec Flow):
|
||||
- Should detect existing patterns
|
||||
- Asks for confirmation before proceeding
|
||||
2. **Review documentation** - Ensure document-project captured patterns
|
||||
3. **Use story-context** - Injects pattern guidance per story
|
||||
4. **Add to code-review checklist**:
|
||||
- Pattern adherence
|
||||
- Convention consistency
|
||||
- Style matching
|
||||
5. **Run retrospective** to identify pattern deviations early
|
||||
|
||||
---
|
||||
|
||||
## File and Path Issues
|
||||
|
||||
### Problem: Output files in wrong location
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- PRD created in wrong folder
|
||||
- Story files not where expected
|
||||
- Documentation scattered
|
||||
|
||||
**Solution:**
|
||||
Check `bmad/bmm/config.yaml` for configured paths:
|
||||
|
||||
```yaml
|
||||
output_folder: '{project-root}/docs'
|
||||
dev_story_location: '{project-root}/docs/stories'
|
||||
```
|
||||
|
||||
Default locations:
|
||||
|
||||
- Planning docs (PRD, epics, architecture): `{output_folder}/`
|
||||
- Stories: `{dev_story_location}/`
|
||||
- Status files: `{output_folder}/bmm-workflow-status.md`, `{output_folder}/sprint-status.yaml`
|
||||
|
||||
To change locations, edit config.yaml then re-run workflows.
|
||||
|
||||
### Problem: Can't find status file
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- workflow-status says no status file
|
||||
- Can't track progress
|
||||
- Lost place in workflow
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check default location**: `docs/bmm-workflow-status.md`
|
||||
2. **If missing, reinitialize**:
|
||||
```
|
||||
Load Analyst agent → run workflow-init
|
||||
```
|
||||
3. **For Phase 4**: Look for `sprint-status.yaml` in same folder as PRD
|
||||
4. **Search for it**:
|
||||
```bash
|
||||
find . -name "bmm-workflow-status.md"
|
||||
find . -name "sprint-status.yaml"
|
||||
```
|
||||
|
||||
### Problem: Sprint-status.yaml not updating
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Workflows complete but status unchanged
|
||||
- Stories stuck in old status
|
||||
- Epic status not progressing
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Manual update required** - Most status changes are manual:
|
||||
```yaml
|
||||
stories:
|
||||
- id: epic-1-story-1
|
||||
status: done # Change this manually
|
||||
```
|
||||
2. **Some workflows auto-update**:
|
||||
- sprint-planning creates file
|
||||
- epic-tech-context changes epic to "contexted"
|
||||
- create-story changes story to "drafted"
|
||||
- story-context changes to "ready-for-dev"
|
||||
- dev-story may auto-update (check workflow)
|
||||
3. **Re-run sprint-planning** to resync if needed
|
||||
|
||||
---
|
||||
|
||||
## Agent Behavior Issues
|
||||
|
||||
### Problem: Agent provides vague or generic responses
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- "Use appropriate framework"
|
||||
- "Follow best practices"
|
||||
- Generic advice without specifics
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Provide more context** - Be specific in your description:
|
||||
- "Add OAuth using passport.js to Express server"
|
||||
- Not: "Add authentication"
|
||||
2. **For brownfield**:
|
||||
- Ensure document-project was run
|
||||
- Agent needs codebase context for specific advice
|
||||
3. **Reference existing docs**:
|
||||
- "Based on the existing auth system in UserService..."
|
||||
4. **Start fresh chat** - Context overload can cause generic responses
|
||||
|
||||
### Problem: Agent hallucinating or making up information
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- References files that don't exist
|
||||
- Suggests APIs that aren't in your stack
|
||||
- Creates imaginary requirements
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Use fresh chat** - Context overflow main cause of hallucinations
|
||||
2. **Provide concrete constraints**:
|
||||
- "We use Express 4.18.2, not Next.js"
|
||||
- "Our database is PostgreSQL, not MongoDB"
|
||||
3. **For brownfield**:
|
||||
- Document-project provides factual grounding
|
||||
- Agent sees actual code, not assumptions
|
||||
4. **Correct immediately**:
|
||||
- "No, we don't have UserService, we have AuthenticationModule"
|
||||
|
||||
### Problem: Agent won't follow instructions
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Ignores specific requests
|
||||
- Does something different than asked
|
||||
- Doesn't respect constraints
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Be more explicit** - Agents respond to clear, specific instructions:
|
||||
- "Use EXACTLY these three steps..."
|
||||
- "Do NOT include database migrations in this story"
|
||||
2. **Check agent capabilities** - Agent might not have access to requested workflow
|
||||
3. **Try different phrasing** - Rephrase request to be more direct
|
||||
4. **Use menu system** - Numbers are clearer than text commands
|
||||
|
||||
---
|
||||
|
||||
## Integration Issues (Brownfield)
|
||||
|
||||
### Problem: New code conflicts with existing architecture
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Integration approach doesn't fit existing structure
|
||||
- Would require major refactoring
|
||||
- Conflicts with established patterns
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check if document-project was run** - Agents need architecture context
|
||||
2. **Review existing architecture docs**:
|
||||
- Read docs/architecture.md (from document-project)
|
||||
- Understand current system design
|
||||
3. **For Level 3-4**:
|
||||
- Run validate-architecture workflow before planning
|
||||
- Use integration-planning workflow
|
||||
4. **Explicitly document integration strategy** in architecture:
|
||||
- How new components fit existing structure
|
||||
- What modifications needed to existing code
|
||||
- Migration path if changing patterns
|
||||
|
||||
### Problem: Breaking changes to existing APIs
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Changing API breaks consumers
|
||||
- Downstream services affected
|
||||
- Need backward compatibility
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Identify all API consumers** (document-project should show this)
|
||||
2. **Plan versioning strategy**:
|
||||
- API v1 (existing) + v2 (new)
|
||||
- Deprecation timeline
|
||||
3. **Use feature flags** for gradual rollout
|
||||
4. **Document migration guide** for API consumers
|
||||
5. **Add to testing strategy**:
|
||||
- Existing consumers still work (v1)
|
||||
- New functionality works (v2)
|
||||
|
||||
### Problem: Data migration required
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Schema changes needed
|
||||
- Existing data needs transformation
|
||||
- Risk of data loss
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Create explicit migration strategy** in architecture:
|
||||
- Forward migration (old → new schema)
|
||||
- Rollback plan (new → old schema)
|
||||
- Data validation approach
|
||||
2. **Test migrations thoroughly**:
|
||||
- On copy of production data
|
||||
- Measure performance impact
|
||||
3. **Plan rollout**:
|
||||
- Staging environment first
|
||||
- Gradual production rollout
|
||||
- Monitoring for issues
|
||||
4. **Document in tech-spec/architecture**:
|
||||
- Migration scripts
|
||||
- Rollback procedures
|
||||
- Expected downtime
|
||||
|
||||
---
|
||||
|
||||
## Still Stuck?
|
||||
|
||||
### Getting More Help
|
||||
|
||||
If your issue isn't covered here:
|
||||
|
||||
1. **Check other documentation**:
|
||||
- [FAQ](./faq.md) - Common questions
|
||||
- [Glossary](./glossary.md) - Terminology
|
||||
- [Quick Start](./quick-start.md) - Basic usage
|
||||
- [Brownfield Guide](./brownfield-guide.md) - Existing codebases
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels
|
||||
|
||||
2. **Community support**:
|
||||
- [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
|
||||
- Active community, fast responses
|
||||
- Share your specific situation
|
||||
|
||||
3. **Report bugs**:
|
||||
- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
- Include version, steps to reproduce, expected vs actual behavior
|
||||
|
||||
4. **Video tutorials**:
|
||||
- [YouTube Channel](https://www.youtube.com/@BMadCode)
|
||||
- Visual walkthroughs of common workflows
|
||||
|
||||
---
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "No workflow status file found"
|
||||
|
||||
**Cause:** Haven't run workflow-init yet
|
||||
**Fix:** Load Analyst agent → run workflow-init
|
||||
|
||||
### "Epic file not found"
|
||||
|
||||
**Cause:** PRD/epics not created, or wrong path
|
||||
**Fix:** Verify PRD/epics exist in output folder, check config.yaml paths
|
||||
|
||||
### "Story not in sprint-status.yaml"
|
||||
|
||||
**Cause:** Sprint-planning not run, or story file not created
|
||||
**Fix:** Run sprint-planning workflow, verify story files exist
|
||||
|
||||
### "Documentation insufficient for brownfield"
|
||||
|
||||
**Cause:** No docs/index.md or document-project not run
|
||||
**Fix:** Run document-project workflow with Deep scan
|
||||
|
||||
### "Level detection failed"
|
||||
|
||||
**Cause:** Ambiguous project description
|
||||
**Fix:** Be more specific, use level keywords (fix, feature, platform, etc.)
|
||||
|
||||
### "Context generation failed"
|
||||
|
||||
**Cause:** Missing prerequisites (epic context, story file, or docs)
|
||||
**Fix:** Verify epic-tech-context run, story file exists, docs present
|
||||
|
||||
---
|
||||
|
||||
## Prevention Tips
|
||||
|
||||
**Avoid common issues before they happen:**
|
||||
|
||||
1. ✅ **Always run document-project for brownfield** - Saves hours of context issues later
|
||||
2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations and context overflow
|
||||
3. ✅ **Verify files exist before running workflows** - Check PRD, epics, stories are present
|
||||
4. ✅ **Read agent menu before requesting workflows** - Confirm agent has the workflow
|
||||
5. ✅ **Start with smaller level if unsure** - Easy to upgrade (Level 1 → 2), hard to downgrade
|
||||
6. ✅ **Keep status files updated** - Manual updates when needed, don't let them drift
|
||||
7. ✅ **Run retrospectives after epics** - Catch issues early, improve next epic
|
||||
8. ✅ **Follow phase sequence** - Don't skip required phases (Phase 2 before 3, 3 before 4)
|
||||
|
||||
---
|
||||
|
||||
**Issue not listed?** Please [report it](https://github.com/bmad-code-org/BMAD-METHOD/issues) so we can add it to this guide!
|
||||
@ -1,685 +1,268 @@
|
||||
# BMM Analysis Workflows (Phase 1)
|
||||
|
||||
**Reading Time:** ~7 minutes
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help you understand your project space before committing to detailed planning. These workflows facilitate creative thinking, market validation, and strategic alignment.
|
||||
Phase 1 (Analysis) workflows are **optional** exploration and discovery tools that help validate ideas, understand markets, and generate strategic context before planning begins.
|
||||
|
||||
**When to use Analysis workflows:**
|
||||
**Key principle:** Analysis workflows help you think strategically before committing to implementation. Skip them if your requirements are already clear.
|
||||
|
||||
- Starting a new project from scratch
|
||||
- Exploring a problem space or opportunity
|
||||
- Validating market fit before significant investment
|
||||
- Gathering strategic context for planning phases
|
||||
**When to use:** Starting new projects, exploring opportunities, validating market fit, generating ideas, understanding problem spaces.
|
||||
|
||||
**When to skip Analysis workflows:**
|
||||
|
||||
- Continuing an existing project with clear requirements
|
||||
- Working on well-defined features with known solutions
|
||||
- Working under strict constraints where discovery is complete
|
||||
**When to skip:** Continuing existing projects with clear requirements, well-defined features with known solutions, strict constraints where discovery is complete.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 Workflow Map
|
||||
## Phase 1 Analysis Workflow Map
|
||||
|
||||
```mermaid
|
||||
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
|
||||
graph TB
|
||||
subgraph Creative["<b>CREATIVE EXPLORATION</b>"]
|
||||
direction TB
|
||||
subgraph Discovery["<b>DISCOVERY & IDEATION (Optional)</b>"]
|
||||
direction LR
|
||||
BrainstormProject["<b>Analyst: brainstorm-project</b><br/>Multi-track solution exploration"]
|
||||
BrainstormGame["<b>Analyst: brainstorm-game</b><br/>Game concept generation"]
|
||||
end
|
||||
|
||||
subgraph Strategic["<b>STRATEGIC PLANNING</b>"]
|
||||
subgraph Research["<b>RESEARCH & VALIDATION (Optional)</b>"]
|
||||
direction TB
|
||||
ProductBrief["<b>Analyst: product-brief</b><br/>Product vision and strategy"]
|
||||
GameBrief["<b>Game Designer: game-brief</b><br/>Game vision capture"]
|
||||
ResearchWF["<b>Analyst: research</b><br/>• market (TAM/SAM/SOM)<br/>• technical (framework evaluation)<br/>• competitive (landscape)<br/>• user (personas, JTBD)<br/>• domain (industry analysis)<br/>• deep_prompt (AI research)"]
|
||||
end
|
||||
|
||||
subgraph Research["<b>RESEARCH AND INVESTIGATION</b>"]
|
||||
direction TB
|
||||
ResearchWF["<b>Analyst: research</b><br/>Market, technical, competitive analysis"]
|
||||
subgraph Strategy["<b>STRATEGIC CAPTURE (Recommended for Greenfield)</b>"]
|
||||
direction LR
|
||||
ProductBrief["<b>Analyst: product-brief</b><br/>Product vision + strategy<br/>(Interactive or YOLO mode)"]
|
||||
GameBrief["<b>Game Designer: game-brief</b><br/>Game vision capture<br/>(Interactive or YOLO mode)"]
|
||||
end
|
||||
|
||||
Creative -.->|Software projects| ProductBrief
|
||||
Creative -.->|Game projects| GameBrief
|
||||
BrainstormProject -.->|May inform| ResearchWF
|
||||
BrainstormGame -.->|May inform| ResearchWF
|
||||
ResearchWF -.->|Feeds into| ProductBrief
|
||||
ResearchWF -.->|Feeds into| GameBrief
|
||||
Discovery -.->|Software| ProductBrief
|
||||
Discovery -.->|Games| GameBrief
|
||||
Discovery -.->|Validate ideas| Research
|
||||
Research -.->|Inform brief| ProductBrief
|
||||
Research -.->|Inform brief| GameBrief
|
||||
ProductBrief --> Phase2["<b>Phase 2: prd workflow</b>"]
|
||||
GameBrief --> Phase2Game["<b>Phase 2: gdd workflow</b>"]
|
||||
Research -.->|Can feed directly| Phase2
|
||||
|
||||
style Creative fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000
|
||||
style Strategic fill:#f3e5f5,stroke:#4a148c,stroke-width:3px,color:#000
|
||||
style Discovery fill:#e1f5fe,stroke:#01579b,stroke-width:3px,color:#000
|
||||
style Research fill:#fff9c4,stroke:#f57f17,stroke-width:3px,color:#000
|
||||
style Strategy fill:#f3e5f5,stroke:#4a148c,stroke-width:3px,color:#000
|
||||
style Phase2 fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
|
||||
style Phase2Game fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
|
||||
|
||||
style BrainstormProject fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000
|
||||
style BrainstormGame fill:#81d4fa,stroke:#0277bd,stroke-width:2px,color:#000
|
||||
style ResearchWF fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000
|
||||
style ProductBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000
|
||||
style GameBrief fill:#ce93d8,stroke:#6a1b9a,stroke-width:2px,color:#000
|
||||
style ResearchWF fill:#fff59d,stroke:#f57f17,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Workflow | Agent | Required | Purpose |
|
||||
| ------------------ | ------------- | ----------- | ----------------------------------------------------------- |
|
||||
| brainstorm-project | Analyst | No | Explore solution approaches and architectures |
|
||||
| brainstorm-game | Analyst | No | Generate game concepts using creative techniques |
|
||||
| product-brief | Analyst | Recommended | Define product vision and strategy |
|
||||
| game-brief | Game Designer | Recommended | Capture game vision before GDD |
|
||||
| research | Analyst | No | Multi-type research system (market, technical, competitive) |
|
||||
| Workflow | Agent | Required | Purpose | Output |
|
||||
| ---------------------- | ------------- | ----------- | -------------------------------------------------------------- | ---------------------------- |
|
||||
| **brainstorm-project** | Analyst | No | Explore solution approaches and architectures | Solution options + rationale |
|
||||
| **brainstorm-game** | Analyst | No | Generate game concepts using creative techniques | Game concepts + evaluation |
|
||||
| **research** | Analyst | No | Multi-type research (market/technical/competitive/user/domain) | Research reports |
|
||||
| **product-brief** | Analyst | Recommended | Define product vision and strategy (interactive) | Product Brief document |
|
||||
| **game-brief** | Game Designer | Recommended | Capture game vision before GDD (interactive) | Game Brief document |
|
||||
|
||||
---
|
||||
|
||||
## brainstorm-project
|
||||
## Workflow Descriptions
|
||||
|
||||
### Purpose
|
||||
### brainstorm-project
|
||||
|
||||
Generate multiple solution approaches for software projects through parallel ideation tracks that align technical and business thinking from inception.
|
||||
**Purpose:** Generate multiple solution approaches through parallel ideation tracks (architecture, UX, integration, value).
|
||||
|
||||
**Agent:** Analyst
|
||||
**Phase:** 1 (Analysis)
|
||||
**Required:** No
|
||||
|
||||
### When to Use
|
||||
**When to Use:**
|
||||
|
||||
- You have a business objective but unclear technical approach
|
||||
- Multiple solution paths exist and you need to evaluate trade-offs
|
||||
- Hidden assumptions need discovery before planning
|
||||
- Innovation beyond obvious solutions is valuable
|
||||
- Unclear technical approach with business objectives
|
||||
- Multiple solution paths need evaluation
|
||||
- Hidden assumptions need discovery
|
||||
- Innovation beyond obvious solutions
|
||||
|
||||
### Prerequisites
|
||||
**Key Outputs:**
|
||||
|
||||
- Business objectives and constraints
|
||||
- Technical environment context
|
||||
- Stakeholder needs identified
|
||||
- Success criteria defined (at least preliminary)
|
||||
- Architecture proposals with trade-off analysis
|
||||
- Value framework (prioritized features)
|
||||
- Risk analysis (dependencies, challenges)
|
||||
- Strategic recommendation with rationale
|
||||
|
||||
### Process Overview
|
||||
|
||||
**1. Context Capture**
|
||||
|
||||
- Business objectives and constraints
|
||||
- Technical environment
|
||||
- Stakeholder needs
|
||||
- Success criteria
|
||||
|
||||
**2. Parallel Ideation**
|
||||
|
||||
- **Architecture Track**: Technical approaches with trade-offs
|
||||
- **UX Track**: Interface paradigms and user journeys
|
||||
- **Integration Track**: System connection patterns
|
||||
- **Value Track**: Feature prioritization and delivery sequences
|
||||
|
||||
**3. Solution Synthesis**
|
||||
|
||||
- Evaluate feasibility and impact
|
||||
- Align with strategic objectives
|
||||
- Surface hidden assumptions
|
||||
- Generate recommendations with rationale
|
||||
|
||||
### Inputs
|
||||
|
||||
| Input | Type | Purpose |
|
||||
| ----------------- | -------- | --------------------------------------------- |
|
||||
| Project Context | Document | Business objectives, environment, constraints |
|
||||
| Problem Statement | Optional | Core challenge or opportunity to address |
|
||||
|
||||
### Outputs
|
||||
|
||||
| Output | Content |
|
||||
| ------------------------ | ------------------------------------------- |
|
||||
| Architecture Proposals | Multiple approaches with trade-off analysis |
|
||||
| Value Framework | Prioritized features aligned to objectives |
|
||||
| Risk Analysis | Dependencies, challenges, opportunities |
|
||||
| Strategic Recommendation | Synthesized direction with rationale |
|
||||
|
||||
### Example Scenario
|
||||
|
||||
**Starting Point:**
|
||||
"We need a customer dashboard for our SaaS product"
|
||||
|
||||
**After brainstorm-project:**
|
||||
|
||||
- **Architecture Option A**: Monolith with server-side rendering (faster to market, easier ops)
|
||||
- **Architecture Option B**: Microservices + SPA (better scalability, more complex)
|
||||
- **Architecture Option C**: Hybrid approach (SSR shell + client-side islands)
|
||||
- **Recommendation**: Option A for MVP, with clear path to Option C as we scale
|
||||
- **Risk**: Option A may require rewrite if we hit 10K+ concurrent users
|
||||
|
||||
### Related Workflows
|
||||
|
||||
- **research** - Deep investigation of market/technical options
|
||||
- **product-brief** - Strategic planning document
|
||||
- **prd** (Phase 2) - Requirements document from chosen approach
|
||||
**Example:** "We need a customer dashboard" → Options: Monolith SSR (faster), Microservices SPA (scalable), Hybrid (balanced) with recommendation.
|
||||
|
||||
---
|
||||
|
||||
## brainstorm-game
|
||||
### brainstorm-game
|
||||
|
||||
### Purpose
|
||||
|
||||
Generate and refine game concepts through systematic creative exploration using five distinct brainstorming techniques, grounded in practical constraints.
|
||||
**Purpose:** Generate game concepts through systematic creative exploration using five brainstorming techniques.
|
||||
|
||||
**Agent:** Analyst
|
||||
**Phase:** 1 (Analysis)
|
||||
**Required:** No
|
||||
|
||||
### When to Use
|
||||
**When to Use:**
|
||||
|
||||
- Generating original game concepts
|
||||
- Exploring variations on a theme
|
||||
- Exploring variations on themes
|
||||
- Breaking creative blocks
|
||||
- Validating game ideas against constraints
|
||||
|
||||
### Prerequisites
|
||||
**Techniques Used:**
|
||||
|
||||
- Platform specifications (mobile, PC, console, web)
|
||||
- Genre preferences or inspirations
|
||||
- Technical constraints understood
|
||||
- Target audience defined
|
||||
- Core design pillars identified (at least preliminary)
|
||||
- SCAMPER (systematic modification)
|
||||
- Mind Mapping (hierarchical exploration)
|
||||
- Lotus Blossom (radial expansion)
|
||||
- Six Thinking Hats (multi-perspective)
|
||||
- Random Word Association (lateral thinking)
|
||||
|
||||
### Process Overview
|
||||
**Key Outputs:**
|
||||
|
||||
**Five Brainstorming Methods** (applied in isolation, then synthesized):
|
||||
- Method-specific artifacts (5 separate documents)
|
||||
- Consolidated concept document with feasibility
|
||||
- Design pillar alignment matrix
|
||||
|
||||
| Method | Focus | Output Characteristics |
|
||||
| ----------------------- | ------------------------ | ---------------------------------- |
|
||||
| SCAMPER | Systematic modification | Structured transformation analysis |
|
||||
| Mind Mapping | Hierarchical exploration | Visual concept relationships |
|
||||
| Lotus Blossom | Radial expansion | Layered thematic development |
|
||||
| Six Thinking Hats | Multi-perspective | Balanced evaluation framework |
|
||||
| Random Word Association | Lateral thinking | Unexpected conceptual combinations |
|
||||
|
||||
Each method generates distinct artifacts that are then evaluated against design pillars, technical feasibility, and market positioning.
|
||||
|
||||
### Inputs
|
||||
|
||||
- **Game Context Document**: Platform specs, genre, technical constraints, target audience, monetization approach, design pillars
|
||||
- **Initial Concept Seed** (optional): High-level game idea or theme
|
||||
|
||||
### Outputs
|
||||
|
||||
- **Method-Specific Artifacts**: Five separate brainstorming documents
|
||||
- **Consolidated Concept Document**: Synthesized game concepts with feasibility assessments and unique value propositions
|
||||
- **Design Pillar Alignment Matrix**: Evaluation of concepts against stated objectives
|
||||
|
||||
### Example Scenario
|
||||
|
||||
**Starting Point:**
|
||||
"A roguelike with psychological themes"
|
||||
|
||||
**After brainstorm-game:**
|
||||
|
||||
- **SCAMPER Result**: "What if standard roguelike death → becomes emotional regression?"
|
||||
- **Mind Map Result**: Emotion types (anger, fear, joy) as character classes
|
||||
- **Lotus Blossom Result**: Inner demons as enemies, therapy sessions as rest points
|
||||
- **Six Thinking Hats Result**: White (data) - mental health market growing; Red (emotion) - theme may alienate hardcore players
|
||||
- **Random Word Association Result**: "Mirror" + "Roguelike" = reflection mechanics that change gameplay
|
||||
|
||||
**Synthesized Concept:**
|
||||
"Mirror of Mind: A roguelike card battler where you play as emotions battling inner demons. Deck composition affects narrative, emotional theme drives mechanics, 3 characters representing anger/fear/joy, target audience: core gamers interested in mental health themes."
|
||||
|
||||
### Related Workflows
|
||||
|
||||
- **game-brief** - Capture validated concept in structured brief
|
||||
- **gdd** (Phase 2) - Full game design document
|
||||
**Example:** "Roguelike with psychological themes" → Emotions as characters, inner demons as enemies, therapy sessions as rest points, deck composition affects narrative.
|
||||
|
||||
---
|
||||
|
||||
## product-brief
|
||||
### research
|
||||
|
||||
### Purpose
|
||||
|
||||
Interactive product brief creation that guides users through defining their product vision with multiple input sources and conversational collaboration.
|
||||
**Purpose:** Comprehensive multi-type research system consolidating market, technical, competitive, user, and domain analysis.
|
||||
|
||||
**Agent:** Analyst
|
||||
**Phase:** 1 (Analysis)
|
||||
**Required:** Recommended (skip only if PRD already exists)
|
||||
|
||||
### When to Use
|
||||
|
||||
- Starting a new product or major feature initiative
|
||||
- Aligning stakeholders before detailed planning
|
||||
- Transitioning from exploration to strategy
|
||||
- Creating executive-level product documentation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Business context understood
|
||||
- Problem or opportunity identified
|
||||
- Stakeholders accessible for input
|
||||
- Strategic objectives defined
|
||||
|
||||
### Modes of Operation
|
||||
|
||||
**Interactive Mode** (Recommended):
|
||||
|
||||
- Step-by-step collaborative development
|
||||
- Probing questions to refine thinking
|
||||
- Deep exploration of problem/solution fit
|
||||
- High-quality output with thorough exploration
|
||||
|
||||
**YOLO Mode**:
|
||||
|
||||
- AI generates complete draft from initial context
|
||||
- User reviews and refines sections iteratively
|
||||
- Faster for rapid draft generation
|
||||
- Best for time-constrained situations or when you have clear vision
|
||||
|
||||
### Process Overview
|
||||
|
||||
**Phase 1: Initialization and Context (Steps 0-2)**
|
||||
|
||||
- Project setup and context capture
|
||||
- Input document gathering
|
||||
- Mode selection
|
||||
- Context extraction
|
||||
|
||||
**Phase 2: Interactive Development (Steps 3-12) - Interactive Mode**
|
||||
|
||||
- Problem definition and pain points
|
||||
- Solution articulation and value proposition
|
||||
- User segmentation
|
||||
- Success metrics and KPIs
|
||||
- MVP scoping (ruthlessly defined)
|
||||
- Financial planning and ROI
|
||||
- Technical context
|
||||
- Risk assessment and assumptions
|
||||
|
||||
**Phase 3: Rapid Generation (Steps 3-4) - YOLO Mode**
|
||||
|
||||
- Complete draft generation from context
|
||||
- Iterative refinement of sections
|
||||
- Quality validation
|
||||
|
||||
**Phase 4: Finalization (Steps 13-15)**
|
||||
|
||||
- Executive summary creation
|
||||
- Supporting materials compilation
|
||||
- Final review and handoff preparation
|
||||
|
||||
### Inputs
|
||||
|
||||
- Optional: Market research, competitive analysis, brainstorming results
|
||||
- User input through conversational process
|
||||
- Business context and objectives
|
||||
|
||||
### Outputs
|
||||
|
||||
**Primary Output:** `product-brief-{project_name}-{date}.md`
|
||||
|
||||
**Output Structure:**
|
||||
|
||||
1. Executive Summary
|
||||
2. Problem Statement (with evidence)
|
||||
3. Proposed Solution (core approach and differentiators)
|
||||
4. Target Users (primary and secondary segments)
|
||||
5. Goals and Success Metrics
|
||||
6. MVP Scope (must-have features)
|
||||
7. Post-MVP Vision
|
||||
8. Financial Impact (investment and ROI)
|
||||
9. Strategic Alignment
|
||||
10. Technical Considerations
|
||||
11. Constraints and Assumptions
|
||||
12. Risks and Open Questions
|
||||
13. Supporting Materials
|
||||
|
||||
### Example Scenario
|
||||
|
||||
**Starting Point:**
|
||||
"We see customers struggling with project tracking"
|
||||
|
||||
**After product-brief (Interactive Mode):**
|
||||
|
||||
- **Problem**: Teams using 3+ tools for project management, causing 40% efficiency loss
|
||||
- **Solution**: Unified workspace combining tasks, docs, and communication
|
||||
- **Target Users**: 10-50 person product teams, SaaS-first companies
|
||||
- **MVP Scope**: Task management + Real-time collaboration + Integrations (GitHub, Slack)
|
||||
- **Success Metrics**: 30% reduction in tool-switching time, 20% faster project completion
|
||||
- **Financial Impact**: $2M investment, $10M ARR target year 2
|
||||
|
||||
### Related Workflows
|
||||
|
||||
- **brainstorm-project** - Generate solution approaches first
|
||||
- **research** - Gather market/competitive intelligence
|
||||
- **prd** (Phase 2) - Detailed requirements from product brief
|
||||
|
||||
---
|
||||
|
||||
## game-brief
|
||||
|
||||
### Purpose
|
||||
|
||||
Lightweight, interactive brainstorming and planning session that captures game vision before diving into detailed Game Design Documents.
|
||||
|
||||
**Agent:** Game Designer
|
||||
**Phase:** 1 (Analysis)
|
||||
**Required:** Recommended for game projects
|
||||
|
||||
### When to Use
|
||||
|
||||
- Starting a new game project from scratch
|
||||
- Exploring a game idea before committing
|
||||
- Pitching a concept to team/stakeholders
|
||||
- Validating market fit and feasibility
|
||||
- Preparing input for GDD workflow
|
||||
|
||||
**Skip if:**
|
||||
|
||||
- You already have a complete GDD
|
||||
- Continuing an existing project
|
||||
- Prototyping without planning needs
|
||||
|
||||
### Comparison: Game Brief vs GDD
|
||||
|
||||
| Aspect | Game Brief | GDD |
|
||||
| ------------ | --------------------------- | ------------------------- |
|
||||
| Purpose | Validate concept | Design for implementation |
|
||||
| Detail Level | High-level vision | Detailed specifications |
|
||||
| Audience | Self, team, stakeholders | Development team |
|
||||
| Scope | Concept validation | Implementation roadmap |
|
||||
| Format | Conversational, exploratory | Structured, comprehensive |
|
||||
| Output | Concise vision document | Comprehensive design doc |
|
||||
|
||||
### Comparison: Game Brief vs Product Brief
|
||||
|
||||
| Aspect | Game Brief | Product Brief |
|
||||
| ------------- | ---------------------------- | --------------------------------- |
|
||||
| Focus | Player experience, fun, feel | User problems, features, value |
|
||||
| Metrics | Engagement, retention, fun | Revenue, conversion, satisfaction |
|
||||
| Core Elements | Gameplay pillars, mechanics | Problem/solution, user segments |
|
||||
| References | Other games | Competitors, market |
|
||||
| Vision | Emotional experience | Business outcomes |
|
||||
|
||||
### Workflow Structure
|
||||
|
||||
**Interactive Mode** (Recommended):
|
||||
|
||||
1. Game Vision (concept, pitch, vision statement)
|
||||
2. Target Market (audience, competition, positioning)
|
||||
3. Game Fundamentals (pillars, mechanics, experience goals)
|
||||
4. Scope and Constraints (platforms, timeline, budget, team)
|
||||
5. Reference Framework (inspiration, competitors, differentiators)
|
||||
6. Content Framework (world, narrative, volume)
|
||||
7. Art and Audio Direction
|
||||
8. Risk Assessment (risks, challenges, mitigation)
|
||||
9. Success Criteria (MVP, metrics, launch goals)
|
||||
10. Next Steps
|
||||
|
||||
**YOLO Mode**: AI generates complete draft, then you refine iteratively
|
||||
|
||||
### Inputs
|
||||
|
||||
Optional:
|
||||
|
||||
- Market research
|
||||
- Brainstorming results
|
||||
- Competitive analysis
|
||||
- Design notes
|
||||
- Reference game lists
|
||||
|
||||
### Outputs
|
||||
|
||||
**Primary Output:** `game-brief-{game_name}-{date}.md`
|
||||
|
||||
**Sections:**
|
||||
|
||||
- Executive summary
|
||||
- Complete game vision
|
||||
- Target market analysis
|
||||
- Core gameplay definition
|
||||
- Scope and constraints
|
||||
- Reference framework
|
||||
- Art/audio direction
|
||||
- Risk assessment
|
||||
- Success criteria
|
||||
- Next steps
|
||||
|
||||
### Example Scenario
|
||||
|
||||
**Starting Point:**
|
||||
"I want to make a roguelike card game with a twist"
|
||||
|
||||
**After Game Brief:**
|
||||
|
||||
- **Core Concept**: Roguelike card battler where you play as emotions battling inner demons
|
||||
- **Target Audience**: Core gamers who love Slay the Spire, interested in mental health themes
|
||||
- **Differentiator**: Emotional narrative system where deck composition affects story
|
||||
- **MVP Scope**: 3 characters, 80 cards, 30 enemy types, 3 bosses, 6-hour first run
|
||||
- **Platform**: PC (Steam) first, mobile later
|
||||
- **Timeline**: 12 months with 2-person team
|
||||
- **Key Risk**: Emotional theme might alienate hardcore roguelike fans
|
||||
- **Mitigation**: Prototype early, test with target audience, offer "mechanical-only" mode
|
||||
|
||||
**Next Steps:**
|
||||
|
||||
1. Build card combat prototype (2 weeks)
|
||||
2. Test emotional resonance with players
|
||||
3. Proceed to GDD workflow if prototype validates
|
||||
|
||||
### Related Workflows
|
||||
|
||||
- **brainstorm-game** - Generate initial concepts
|
||||
- **gdd** (Phase 2) - Full game design document
|
||||
- **narrative** (Phase 2) - For story-heavy games
|
||||
|
||||
---
|
||||
|
||||
## research
|
||||
|
||||
### Purpose
|
||||
|
||||
Comprehensive, adaptive multi-type research system that consolidates various research methodologies into a single powerful tool.
|
||||
|
||||
**Agent:** Analyst
|
||||
**Phase:** 1 (Analysis)
|
||||
**Required:** No
|
||||
|
||||
### Research Types
|
||||
|
||||
**6 Research Types Available:**
|
||||
**Research Types:**
|
||||
|
||||
| Type | Purpose | Use When |
|
||||
| --------------- | ------------------------------------------------------ | ----------------------------------- |
|
||||
| **market** | Market intelligence, TAM/SAM/SOM, competitive analysis | Need market viability validation |
|
||||
| **deep_prompt** | Generate optimized research prompts for AI platforms | Need AI to research deeper topics |
|
||||
| **technical** | Technology evaluation, architecture decisions | Choosing frameworks/platforms |
|
||||
| **market** | TAM/SAM/SOM, competitive analysis | Need market viability validation |
|
||||
| **technical** | Technology evaluation, ADRs | Choosing frameworks/platforms |
|
||||
| **competitive** | Deep competitor analysis | Understanding competitive landscape |
|
||||
| **user** | Customer insights, personas, JTBD | Need user understanding |
|
||||
| **domain** | Industry deep dives, trends | Understanding domain/industry |
|
||||
|
||||
### Market Research (Type: market)
|
||||
| **deep_prompt** | Generate AI research prompts (ChatGPT, Claude, Gemini) | Need deeper AI-assisted research |
|
||||
|
||||
**Key Features:**
|
||||
|
||||
- Real-time web research
|
||||
- TAM/SAM/SOM calculations with multiple methodologies
|
||||
- Competitive landscape analysis
|
||||
- Customer persona development
|
||||
- Porter's Five Forces and strategic frameworks
|
||||
- Go-to-market strategy recommendations
|
||||
- Multiple analytical frameworks (Porter's Five Forces, SWOT, Technology Adoption Lifecycle)
|
||||
- Platform-specific optimization for deep_prompt type
|
||||
- Configurable research depth (quick/standard/comprehensive)
|
||||
|
||||
**Inputs:**
|
||||
|
||||
- Product or business description
|
||||
- Target customer hypotheses (optional)
|
||||
- Known competitors list (optional)
|
||||
|
||||
**Outputs:**
|
||||
|
||||
- Market size analysis (TAM/SAM/SOM)
|
||||
- Competitive positioning
|
||||
- Customer segments and personas
|
||||
- Market trends and opportunities
|
||||
- Strategic recommendations
|
||||
- Financial projections (optional)
|
||||
|
||||
### Deep Research Prompt (Type: deep_prompt)
|
||||
|
||||
**Key Features:**
|
||||
|
||||
- Optimized for AI research platforms (ChatGPT Deep Research, Gemini, Grok, Claude Projects)
|
||||
- Prompt engineering best practices
|
||||
- Platform-specific optimization
|
||||
- Context packaging for optimal AI understanding
|
||||
- Research question refinement
|
||||
|
||||
**Inputs:**
|
||||
|
||||
- Research question or topic
|
||||
- Background context documents (optional)
|
||||
- Target AI platform preference (optional)
|
||||
|
||||
**Outputs:**
|
||||
|
||||
- Platform-optimized research prompt
|
||||
- Multi-stage research workflow
|
||||
- Context documents packaged
|
||||
- Execution guidance
|
||||
|
||||
### Technical Research (Type: technical)
|
||||
|
||||
**Key Features:**
|
||||
|
||||
- Technology evaluation and comparison matrices
|
||||
- Architecture pattern research
|
||||
- Framework/library assessment
|
||||
- Technical feasibility studies
|
||||
- Cost-benefit analysis
|
||||
- Architecture Decision Records (ADR)
|
||||
|
||||
**Inputs:**
|
||||
|
||||
- Technical requirements
|
||||
- Current architecture (if brownfield)
|
||||
- Technical constraints
|
||||
|
||||
**Outputs:**
|
||||
|
||||
- Technology comparison matrix
|
||||
- Trade-off analysis
|
||||
- Cost-benefit assessment
|
||||
- ADR with recommendation
|
||||
- Implementation guidance
|
||||
|
||||
### Configuration Options
|
||||
|
||||
Can be customized through workflow.yaml:
|
||||
|
||||
- **research_depth**: `quick`, `standard`, or `comprehensive`
|
||||
- **enable_web_research**: Enable real-time data gathering
|
||||
- **enable_competitor_analysis**: Competitive intelligence
|
||||
- **enable_financial_modeling**: Financial projections
|
||||
|
||||
### Frameworks Available
|
||||
|
||||
**Market Research:**
|
||||
|
||||
- TAM/SAM/SOM Analysis
|
||||
- Porter's Five Forces
|
||||
- Jobs-to-be-Done (JTBD)
|
||||
- Technology Adoption Lifecycle
|
||||
- SWOT Analysis
|
||||
- Value Chain Analysis
|
||||
|
||||
**Technical Research:**
|
||||
|
||||
- Trade-off Analysis Matrix
|
||||
- Architecture Decision Records (ADR)
|
||||
- Technology Radar
|
||||
- Comparison Matrix
|
||||
- Cost-Benefit Analysis
|
||||
- Technical Risk Assessment
|
||||
|
||||
### Example Scenario
|
||||
|
||||
**Type: market**
|
||||
|
||||
**Input:**
|
||||
"SaaS project management tool for remote teams"
|
||||
|
||||
**Output:**
|
||||
|
||||
- **TAM**: $50B (global project management software)
|
||||
- **SAM**: $5B (remote-first teams 10-50 people)
|
||||
- **SOM**: $50M (achievable in year 3)
|
||||
- **Top Competitors**: Asana, Monday.com, ClickUp
|
||||
- **Positioning**: "Real-time collaboration focused, vs async-first competitors"
|
||||
- **Customer Personas**: Product Managers (primary), Engineering Leads (secondary)
|
||||
- **Key Trends**: Remote work permanence, tool consolidation, AI features
|
||||
- **Go-to-Market**: PLG motion, free tier, viral invite mechanics
|
||||
|
||||
### Related Workflows
|
||||
|
||||
- **product-brief** - Use research to inform brief
|
||||
- **prd** (Phase 2) - Research feeds requirements
|
||||
- **architecture** (Phase 3) - Technical research informs design
|
||||
**Example (market):** "SaaS project management tool" → TAM $50B, SAM $5B, SOM $50M, top competitors (Asana, Monday), positioning recommendation.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices for Phase 1
|
||||
### product-brief
|
||||
|
||||
### 1. Don't Over-Invest in Analysis
|
||||
**Purpose:** Interactive product brief creation that guides strategic product vision definition.
|
||||
|
||||
Analysis workflows are optional for a reason. If you already know what you're building and why, skip to Phase 2 (Planning).
|
||||
**Agent:** Analyst
|
||||
|
||||
### 2. Iterate Between Workflows
|
||||
**When to Use:**
|
||||
|
||||
It's common to:
|
||||
- Starting new product/major feature initiative
|
||||
- Aligning stakeholders before detailed planning
|
||||
- Transitioning from exploration to strategy
|
||||
- Need executive-level product documentation
|
||||
|
||||
1. Run **brainstorm-project** to explore
|
||||
2. Use **research** to validate
|
||||
3. Create **product-brief** to synthesize
|
||||
**Modes:**
|
||||
|
||||
### 3. Document Assumptions
|
||||
- **Interactive Mode** (Recommended): Step-by-step collaborative development with probing questions
|
||||
- **YOLO Mode**: AI generates complete draft from context, then iterative refinement
|
||||
|
||||
Analysis phase is about surfacing and validating assumptions. Document them explicitly so planning can challenge them.
|
||||
**Key Outputs:**
|
||||
|
||||
### 4. Keep It Strategic
|
||||
- Executive summary
|
||||
- Problem statement with evidence
|
||||
- Proposed solution and differentiators
|
||||
- Target users (segmented)
|
||||
- MVP scope (ruthlessly defined)
|
||||
- Financial impact and ROI
|
||||
- Strategic alignment
|
||||
- Risks and open questions
|
||||
|
||||
Analysis workflows focus on "what" and "why", not "how". Leave implementation details for Planning and Solutioning phases.
|
||||
|
||||
### 5. Involve Stakeholders
|
||||
|
||||
Analysis workflows are collaborative. Use them to align stakeholders before committing to detailed planning.
|
||||
**Integration:** Feeds directly into PRD workflow (Phase 2).
|
||||
|
||||
---
|
||||
|
||||
## Decision Guide: Which Analysis Workflow?
|
||||
### game-brief
|
||||
|
||||
**Purpose:** Lightweight interactive brainstorming session capturing game vision before Game Design Document.
|
||||
|
||||
**Agent:** Game Designer
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Starting new game project
|
||||
- Exploring game ideas before committing
|
||||
- Pitching concepts to team/stakeholders
|
||||
- Validating market fit and feasibility
|
||||
|
||||
**Game Brief vs GDD:**
|
||||
|
||||
| Aspect | Game Brief | GDD |
|
||||
| ------------ | ------------------ | ------------------------- |
|
||||
| Purpose | Validate concept | Design for implementation |
|
||||
| Detail Level | High-level vision | Detailed specs |
|
||||
| Format | Conversational | Structured |
|
||||
| Output | Concise vision doc | Comprehensive design |
|
||||
|
||||
**Key Outputs:**
|
||||
|
||||
- Game vision (concept, pitch)
|
||||
- Target market and positioning
|
||||
- Core gameplay pillars
|
||||
- Scope and constraints
|
||||
- Reference framework
|
||||
- Risk assessment
|
||||
- Success criteria
|
||||
|
||||
**Integration:** Feeds into GDD workflow (Phase 2).
|
||||
|
||||
---
|
||||
|
||||
## Decision Guide
|
||||
|
||||
### Starting a Software Project
|
||||
|
||||
1. **brainstorm-project** (if unclear solution) → **research** (market/technical) → **product-brief**
|
||||
```
|
||||
brainstorm-project (if unclear) → research (market/technical) → product-brief → Phase 2 (prd)
|
||||
```
|
||||
|
||||
### Starting a Game Project
|
||||
|
||||
1. **brainstorm-game** (if generating concepts) → **research** (market/competitive) → **game-brief**
|
||||
```
|
||||
brainstorm-game (if generating concepts) → research (market/competitive) → game-brief → Phase 2 (gdd)
|
||||
```
|
||||
|
||||
### Validating an Idea
|
||||
|
||||
1. **research** (market type) → **product-brief** or **game-brief**
|
||||
```
|
||||
research (market type) → product-brief or game-brief → Phase 2
|
||||
```
|
||||
|
||||
### Technical Decision
|
||||
### Technical Decision Only
|
||||
|
||||
1. **research** (technical type) → Use ADR in **architecture** (Phase 3)
|
||||
```
|
||||
research (technical type) → Use findings in Phase 3 (architecture)
|
||||
```
|
||||
|
||||
### Understanding Market
|
||||
|
||||
1. **research** (market or competitive type) → **product-brief**
|
||||
|
||||
### Generating Deep Research
|
||||
|
||||
1. **research** (deep_prompt type) → External AI research platform → Return with findings
|
||||
```
|
||||
research (market/competitive type) → product-brief → Phase 2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Phase 2 (Planning)
|
||||
|
||||
Analysis workflows feed directly into Planning:
|
||||
Analysis outputs feed directly into Planning:
|
||||
|
||||
| Analysis Output | Planning Input |
|
||||
| --------------------------- | -------------------------- |
|
||||
@ -689,18 +272,99 @@ Analysis workflows feed directly into Planning:
|
||||
| technical-research.md | **architecture** (Phase 3) |
|
||||
| competitive-intelligence.md | **prd** positioning |
|
||||
|
||||
The Planning phase (Phase 2) will load these documents automatically if they exist in the output folder.
|
||||
Planning workflows automatically load these documents if they exist in the output folder.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
## Best Practices
|
||||
|
||||
Phase 1 Analysis workflows are your strategic thinking tools. Use them to:
|
||||
### 1. Don't Over-Invest in Analysis
|
||||
|
||||
- **Explore** problem spaces and solutions
|
||||
- **Validate** ideas before heavy investment
|
||||
- **Align** stakeholders on vision
|
||||
- **Research** markets, competitors, and technologies
|
||||
- **Document** strategic thinking for future reference
|
||||
Analysis is optional. If requirements are clear, skip to Phase 2 (Planning).
|
||||
|
||||
Remember: **These workflows are optional.** If you know what you're building and why, skip to Phase 2 (Planning) to define requirements and create your PRD/GDD.
|
||||
### 2. Iterate Between Workflows
|
||||
|
||||
Common pattern: brainstorm → research (validate) → brief (synthesize)
|
||||
|
||||
### 3. Document Assumptions
|
||||
|
||||
Analysis surfaces and validates assumptions. Document them explicitly for planning to challenge.
|
||||
|
||||
### 4. Keep It Strategic
|
||||
|
||||
Focus on "what" and "why", not "how". Leave implementation for Planning and Solutioning.
|
||||
|
||||
### 5. Involve Stakeholders
|
||||
|
||||
Use analysis workflows to align stakeholders before committing to detailed planning.
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Greenfield Software (Full Analysis)
|
||||
|
||||
```
|
||||
1. brainstorm-project - explore approaches
|
||||
2. research (market) - validate viability
|
||||
3. product-brief - capture strategic vision
|
||||
4. → Phase 2: prd
|
||||
```
|
||||
|
||||
### Greenfield Game (Full Analysis)
|
||||
|
||||
```
|
||||
1. brainstorm-game - generate concepts
|
||||
2. research (competitive) - understand landscape
|
||||
3. game-brief - capture vision
|
||||
4. → Phase 2: gdd
|
||||
```
|
||||
|
||||
### Skip Analysis (Clear Requirements)
|
||||
|
||||
```
|
||||
→ Phase 2: prd or tech-spec directly
|
||||
```
|
||||
|
||||
### Technical Research Only
|
||||
|
||||
```
|
||||
1. research (technical) - evaluate technologies
|
||||
2. → Phase 3: architecture (use findings in ADRs)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Phase 2: Planning Workflows](./workflows-planning.md) - Next phase
|
||||
- [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
|
||||
- [Phase 4: Implementation Workflows](./workflows-implementation.md)
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project complexity
|
||||
- [Agents Guide](./agents-guide.md) - Complete agent reference
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Q: Do I need to run all analysis workflows?**
|
||||
A: No! Analysis is entirely optional. Use only workflows that help you think through your problem.
|
||||
|
||||
**Q: Which workflow should I start with?**
|
||||
A: If unsure, start with `research` (market type) to validate viability, then move to `product-brief` or `game-brief`.
|
||||
|
||||
**Q: Can I skip straight to Planning?**
|
||||
A: Yes! If you know what you're building and why, skip Phase 1 entirely and start with Phase 2 (prd/gdd/tech-spec).
|
||||
|
||||
**Q: How long should Analysis take?**
|
||||
A: Typically hours to 1-2 days. If taking longer, you may be over-analyzing. Move to Planning.
|
||||
|
||||
**Q: What if I discover problems during Analysis?**
|
||||
A: That's the point! Analysis helps you fail fast and pivot before heavy planning investment.
|
||||
|
||||
**Q: Should brownfield projects do Analysis?**
|
||||
A: Usually no. Start with `document-project` (Phase 0), then skip to Planning (Phase 2).
|
||||
|
||||
---
|
||||
|
||||
_Phase 1 Analysis - Optional strategic thinking before commitment._
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -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._
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user