ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refined the docs for test architect

Browse Source
This commit is contained in:
Murat Ozcan
2025-08-13 11:07:22 -05:00
parent 34e75bef96
commit 8d300dadf3
3 changed files with 585 additions and 249 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
docs/enhanced-ide-development-workflow.md
View File

@@ -1,8 +1,8 @@
# Enhanced Development Workflow
# Enhanced IDE Development Workflow
This is a simple step-by-step guide to help you efficiently manage your development workflow using the BMad Method. Refer to the **[<ins>User Guide</ins>](user-guide.md)** for any scenario that is not covered here.
This is a simple step-by-step guide to help you efficiently manage your development workflow using the BMad Method. The workflow integrates the Test Architect (QA agent) throughout the development lifecycle to ensure quality, prevent regressions, and maintain high standards. Refer to the **[<ins>User Guide</ins>](user-guide.md)** for any scenario that is not covered here.
## Create new Branch
## Create New Branch
1. **Start new branch**
@@ -23,101 +23,226 @@ This is a simple step-by-step guide to help you efficiently manage your developm
## Test Architect Integration Throughout Workflow
The Test Architect (Quinn) provides comprehensive quality assurance throughout the development lifecycle. Here's how to leverage each capability at the right time.
**Command Aliases:** Documentation uses short forms (`*risk`, `*design`, `*nfr`, `*trace`) for the full commands (`*risk-profile`, `*test-design`, `*nfr-assess`, `*trace-requirements`).
### Quick Command Reference
| **Stage** | **Command** | **Purpose** | **Output** | **Priority** |
|-----------|------------|-------------|------------|--------------|
| **After Story Approval** | `*risk` | Identify integration & regression risks | `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md` | High for complex/brownfield |
| | `*design` | Create test strategy for dev | `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md` | High for new features |
| **During Development** | `*trace` | Verify test coverage | `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md` | Medium |
| | `*nfr` | Validate quality attributes | `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md` | High for critical features |
| **After Development** | `*review` | Comprehensive assessment | QA Results in story + `docs/qa/gates/{epic}.{story}-{slug}.yml` | **Required** |
| **Post-Review** | `*gate` | Update quality decision | Updated `docs/qa/gates/{epic}.{story}-{slug}.yml` | As needed |
### Stage 1: After Story Creation (Before Dev Starts)
**Optional but Valuable - Set Dev Up for Success:**
**RECOMMENDED - Set Developer Up for Success:**
```bash
# Design test strategy for developer
@qa *design {approved-story}
# Output: docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
# Why: Gives Dev clear test requirements upfront
# Identify risks to watch for
# 1. RISK ASSESSMENT (Run FIRST for complex stories)
@qa *risk {approved-story}
# Output: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
# Why: Helps Dev avoid critical issues and focus on risk areas
# Identifies:
# - Technical debt impact
# - Integration complexity
# - Regression potential (1-9 scoring)
# - Mitigation strategies
# Critical for: Brownfield, API changes, data migrations
# 2. TEST DESIGN (Run SECOND to guide implementation)
@qa *design {approved-story}
# Provides:
# - Test scenarios per acceptance criterion
# - Test level recommendations (unit/integration/E2E)
# - Risk-based priorities (P0/P1/P2)
# - Test data requirements
# Share with Dev: Include in story comments or attach to ticket
```
### Stage 2: During Development (Optional Checkpoints)
### Stage 2: During Development (Mid-Implementation Checkpoints)
**Dev Can Self-Check Progress:**
**Developer Self-Service Quality Checks:**
```bash
# Validate NFRs mid-implementation
@qa *nfr {story-in-progress}
# Output: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
# Why: Catch performance/security issues early
# Verify test coverage while developing
# 3. REQUIREMENTS TRACING (Verify coverage mid-development)
@qa *trace {story-in-progress}
# Output: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
# Why: Ensure you're writing the right tests
# Validates:
# - All acceptance criteria have tests
# - No missing test scenarios
# - Appropriate test levels
# - Given-When-Then documentation clarity
# Run when: After writing initial tests
# 4. NFR VALIDATION (Check quality attributes)
@qa *nfr {story-in-progress}
# Assesses:
# - Security: Authentication, authorization, data protection
# - Performance: Response times, resource usage
# - Reliability: Error handling, recovery
# - Maintainability: Code quality, documentation
# Run when: Before marking "Ready for Review"
```
### Stage 3: Story Review (Required)
### Stage 3: Story Review (Quality Gate Assessment)
**Standard Review Flow:**
**REQUIRED - Comprehensive Test Architecture Review:**
1. **Start new chat/conversation**
2. **Load QA agent** (Test Architect - Quinn)
3. **Execute**: `@qa *review {selected-story}`
4. **Review outputs**:
- QA Results section added to story file
- Quality gate file in `docs/qa/gates/{epic}.{story}-{slug}.yml`
**If Issues Found:**
**Prerequisite:** All tests green locally; lint & type checks pass.
```bash
# After fixes, update gate status
@qa *gate {reviewed-story}
# Output: Updates docs/qa/gates/{epic}.{story}-{slug}.yml
# 5. FULL REVIEW (Standard review process)
@qa *review {completed-story}
```
### Special Situations
**What Happens During Review:**
**High-Risk Stories or Brownfield:**
1. **Deep Code Analysis**
- Architecture pattern compliance
- Code quality and maintainability
- Security vulnerability scanning
- Performance bottleneck detection
- Always run `*risk` and `*design` before development
- Extra focus on regression testing
2. **Active Refactoring**
- Improves code directly when safe
- Fixes obvious issues immediately
- Suggests complex refactoring for dev
**Complex Integrations:**
3. **Test Validation**
- Coverage at all levels (unit/integration/E2E)
- Test quality (no flaky tests, proper assertions)
- Regression test adequacy
- Run `*trace` to ensure all integration points tested
- Consider `*nfr` for performance validation
4. **Gate Decision**
- Creates: `docs/qa/gates/{epic}.{story}-{slug}.yml`
- Adds: QA Results section to story file
- Status: PASS/CONCERNS/FAIL/WAIVED
**Performance-Critical Features:**
### Stage 4: Post-Review (After Addressing Issues)
- Run `*nfr` during development, not just at review
- Set performance baselines early
**Update Gate Status After Fixes:**
```bash
# 6. GATE UPDATE (Document final decision)
@qa *gate {reviewed-story}
# Updates: Quality gate with new status
# Use when: After addressing review feedback
# Documents: What was fixed, what was waived
```
### Understanding Gate Decisions
- **PASS**: Ready for production, all quality criteria met
- **CONCERNS**: Non-critical issues to review with team
- **FAIL**: Critical issues must be fixed (security, missing tests)
- **WAIVED**: Known issues accepted by team with documentation
| **Status** | **Meaning** | **Action Required** | **Can Proceed?** |
|------------|-------------|-------------------|------------------|
| **PASS** | All critical requirements met | None | ✅ Yes |
| **CONCERNS** | Non-critical issues found | Team review recommended | ⚠️ With caution |
| **FAIL** | Critical issues (security, missing P0 tests) | Must fix | ❌ No |
| **WAIVED** | Issues acknowledged and accepted | Document reasoning | ✅ With approval |
### What Quinn Does During Review
### Risk-Based Testing Strategy
1. **Analyzes code quality** and architecture patterns
2. **Actively refactors** code when safe to do so
3. **Validates test coverage** at appropriate levels
4. **Identifies risks** (security, performance, data)
5. **Checks NFRs** against standards
6. **Creates quality gate** with clear decision criteria
7. **Documents everything** for audit trail
The Test Architect uses risk scoring to prioritize testing:
| **Risk Score** | **Calculation** | **Testing Priority** | **Gate Impact** |
|---------------|----------------|-------------------|----------------|
| **9** | High probability × High impact | P0 - Must test thoroughly | FAIL if untested |
| **6** | Medium-high combinations | P1 - Should test well | CONCERNS if gaps |
| **4** | Medium combinations | P1 - Should test | CONCERNS if notable gaps |
| **2-3** | Low-medium combinations | P2 - Nice to have | Note in review |
| **1** | Minimal risk | P2 - Minimal | Note in review |
### Special Situations & Best Practices
#### High-Risk or Brownfield Stories
```bash
# ALWAYS run this sequence:
@qa *risk {story} # First - identify dangers
@qa *design {story} # Second - plan defense
# Then during dev:
@qa *trace {story} # Verify regression coverage
@qa *nfr {story} # Check performance impact
# Finally:
@qa *review {story} # Deep integration analysis
```
#### Complex Integrations
- Run `*trace` multiple times during development
- Focus on integration test coverage
- Use `*nfr` to validate cross-system performance
- Review with extra attention to API contracts
#### Performance-Critical Features
- Run `*nfr` early and often (not just at review)
- Establish performance baselines before changes
- Document acceptable performance degradation
- Consider load testing requirements in `*design`
### Test Quality Standards Enforced
Quinn ensures all tests meet these standards:
- **No Flaky Tests**: Proper async handling, explicit waits
- **No Hard Waits**: Dynamic strategies only (polling, events)
- **Stateless**: Tests run independently and in parallel
- **Self-Cleaning**: Tests manage their own test data
- **Appropriate Levels**: Unit for logic, integration for interactions, E2E for journeys
- **Clear Assertions**: Keep assertions in tests, not buried in helpers
### Documentation & Audit Trail
All Test Architect activities create permanent records:
- **Assessment Reports**: Timestamped analysis in `docs/qa/assessments/`
- **Gate Files**: Decision records in `docs/qa/gates/`
- **Story Updates**: QA Results sections in story files
- **Traceability**: Requirements to test mapping maintained
## Commit Changes and Push
1. **Commit changes**
2. **Push to remote**
## Repeat Until Complete
## Complete Development Cycle Flow
- **SM**: Create next story → Review → Approve
- **Dev**: Implement story → Complete → Mark Ready for Review
- **QA**: Review story → Mark done
- **Commit**: All changes
- **Push**: To remote
- **Continue**: Until all features implemented
### The Full Workflow with Test Architect
1. **SM**: Create next story → Review → Approve
2. **QA (Optional)**: Risk assessment (`*risk`) → Test design (`*design`)
3. **Dev**: Implement story → Write tests → Complete
4. **QA (Optional)**: Mid-dev checks (`*trace`, `*nfr`)
5. **Dev**: Mark Ready for Review
6. **QA (Required)**: Review story (`*review`) → Gate decision
7. **Dev (If needed)**: Address issues
8. **QA (If needed)**: Update gate (`*gate`)
9. **Commit**: All changes
10. **Push**: To remote
11. **Continue**: Until all features implemented
### Quick Decision Guide
**Should I run Test Architect commands?**
| **Scenario** | **Before Dev** | **During Dev** | **After Dev** |
|-------------|---------------|----------------|---------------|
| **Simple bug fix** | Optional | Optional | Required `*review` |
| **New feature** | Recommended `*risk`, `*design` | Optional `*trace` | Required `*review` |
| **Brownfield change** | **Required** `*risk`, `*design` | Recommended `*trace`, `*nfr` | Required `*review` |
| **API modification** | **Required** `*risk`, `*design` | **Required** `*trace` | Required `*review` |
| **Performance-critical** | Recommended `*design` | **Required** `*nfr` | Required `*review` |
| **Data migration** | **Required** `*risk`, `*design` | **Required** `*trace` | Required `*review` + `*gate` |
### Success Metrics
The Test Architect helps achieve:
- **Zero regression defects** in production
- **100% requirements coverage** with tests
- **Clear quality gates** for go/no-go decisions
- **Documented risk acceptance** for technical debt
- **Consistent test quality** across the team
- **Shift-left testing** with early risk identification