BMAD-METHOD/docs/enhanced-ide-development-workflow.md

Enhanced IDE Development Workflow

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 User Guide for any scenario that is not covered here.

Create New Branch

1. Start new branch

Story Creation (Scrum Master)

1. Start new chat/conversation
2. Load SM agent
3. Execute: *draft (runs create-next-story task)
4. Review generated story in docs/stories/
5. Update status: Change from "Draft" to "Approved"

Story Implementation (Developer)

1. Start new chat/conversation
2. Load Dev agent
3. Execute: *develop-story {selected-story} (runs execute-checklist task)
4. Review generated report in {selected-story}

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)

RECOMMENDED - Set Developer Up for Success:

# 1. RISK ASSESSMENT (Run FIRST for complex stories)
@qa *risk {approved-story}
# 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 (Mid-Implementation Checkpoints)

Developer Self-Service Quality Checks:

# 3. REQUIREMENTS TRACING (Verify coverage mid-development)
@qa *trace {story-in-progress}
# 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 (Quality Gate Assessment)

REQUIRED - Comprehensive Test Architecture Review:

Prerequisite: All tests green locally; lint & type checks pass.

# 5. FULL REVIEW (Standard review process)
@qa *review {completed-story}

What Happens During Review:

1. Deep Code Analysis

   • Architecture pattern compliance
   • Code quality and maintainability
   • Security vulnerability scanning
   • Performance bottleneck detection

2. Active Refactoring

   • Improves code directly when safe
   • Fixes obvious issues immediately
   • Suggests complex refactoring for dev

3. Test Validation

   • Coverage at all levels (unit/integration/E2E)
   • Test quality (no flaky tests, proper assertions)
   • Regression test adequacy

4. Gate Decision

   • Creates: docs/qa/gates/{epic}.{story}-{slug}.yml
   • Adds: QA Results section to story file
   • Status: PASS/CONCERNS/FAIL/WAIVED

Stage 4: Post-Review (After Addressing Issues)

Update Gate Status After Fixes:

# 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

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

Risk-Based Testing Strategy

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

# 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

Complete Development Cycle Flow

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