docs: refined the docs for test architect

docs/enhanced-ide-development-workflow.md

@@ -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
+# 1. RISK ASSESSMENT (Run FIRST for complex stories)
-@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
 @qa *risk {approved-story}
-# Output: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+# Identifies:
-# Why: Helps Dev avoid critical issues and focus on risk areas
+#   - 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
+# 3. REQUIREMENTS TRACING (Verify coverage mid-development)
-@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
 @qa *trace {story-in-progress}
-# Output: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
+# Validates:
-# Why: Ensure you're writing the right tests
+#   - 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**
+**Prerequisite:** All tests green locally; lint & type checks pass.
-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:**
 
 ```bash
-# After fixes, update gate status
+# 5. FULL REVIEW (Standard review process)
-@qa *gate {reviewed-story}
+@qa *review {completed-story}
-# Output: Updates docs/qa/gates/{epic}.{story}-{slug}.yml
 ```
 
-### 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
+2. **Active Refactoring**
-- Extra focus on regression testing
+   - 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
+4. **Gate Decision**
-- Consider `*nfr` for performance validation
+   - 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
+**Update Gate Status After Fixes:**
-- Set performance baselines early
+
+```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
+| **Status** | **Meaning** | **Action Required** | **Can Proceed?** |
-- **CONCERNS**: Non-critical issues to review with team
+|------------|-------------|-------------------|------------------|
-- **FAIL**: Critical issues must be fixed (security, missing tests)
+| **PASS** | All critical requirements met | None | ✅ Yes |
-- **WAIVED**: Known issues accepted by team with documentation
+| **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
+The Test Architect uses risk scoring to prioritize testing:
-2. **Actively refactors** code when safe to do so
+
-3. **Validates test coverage** at appropriate levels
+| **Risk Score** | **Calculation** | **Testing Priority** | **Gate Impact** |
-4. **Identifies risks** (security, performance, data)
+|---------------|----------------|-------------------|----------------|
-5. **Checks NFRs** against standards
+| **9** | High probability × High impact | P0 - Must test thoroughly | FAIL if untested |
-6. **Creates quality gate** with clear decision criteria
+| **6** | Medium-high combinations | P1 - Should test well | CONCERNS if gaps |
-7. **Documents everything** for audit trail
+| **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
+### The Full Workflow with Test Architect
-- **Dev**: Implement story → Complete → Mark Ready for Review
+
-- **QA**: Review story → Mark done
+1. **SM**: Create next story → Review → Approve
-- **Commit**: All changes
+2. **QA (Optional)**: Risk assessment (`*risk`) → Test design (`*design`)
-- **Push**: To remote
+3. **Dev**: Implement story → Write tests → Complete
-- **Continue**: Until all features implemented
+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

docs/user-guide.md

@@ -1,6 +1,6 @@
-# BMad-Method BMAd Code User Guide
+# BMad Method — User Guide
 
-This guide will help you understand and effectively use the BMad Method for agile AI driven planning and development.
+This guide will help you understand and effectively use the BMad Method for agile AI-driven planning and development.
 
 ## The BMad Plan and Execute Workflow
 
@@ -8,7 +8,7 @@ First, here is the full standard Greenfield Planning + Execution Workflow. Brown
 
 If you are going to use the BMad Method with a Brownfield project (an existing project), review **[Working in the Brownfield](./working-in-the-brownfield.md)**.
 
-If you do not see the diagrams that following rendering, you can install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugin's, if you right click on the tab when open, there should be a Open Preview option, or check the IDE documentation.
+If the diagrams below don't render, install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugins, if you right click on the tab when open, there should be an Open Preview option, or check the IDE documentation.
 
 ### The Planning Workflow (Web UI or Powerful IDE Agents)
 
@@ -32,8 +32,11 @@ graph TD
     F2 -->|No| H["Architect: Create Architecture from PRD"]
     F3 --> F4["UX Expert: Generate UI Prompt for Lovable/V0 (Optional)"]
     F4 --> H2["Architect: Create Architecture from PRD + UX Spec"]
-    H --> I["PO: Run Master Checklist"]
+    H --> Q{"Early Test Strategy? (Optional)"}
-    H2 --> I
+    H2 --> Q
+    Q -->|Yes| R["QA: Early Test Architecture Input on High-Risk Areas"]
+    Q -->|No| I
+    R --> I["PO: Run Master Checklist"]
     I --> J{"Documents Aligned?"}
     J -->|Yes| K["Planning Complete"]
     J -->|No| L["PO: Update Epics & Stories"]
@@ -58,6 +61,8 @@ graph TD
     style G fill:#e3f2fd,color:#000
     style H fill:#f3e5f5,color:#000
     style H2 fill:#f3e5f5,color:#000
+    style Q fill:#e3f2fd,color:#000
+    style R fill:#ffd54f,color:#000
     style I fill:#f9ab00,color:#fff
     style J fill:#e3f2fd,color:#000
     style K fill:#34a853,color:#fff
@@ -77,6 +82,17 @@ graph TD
 3. **Document Sharding**: Use the PO agent to shard the PRD and then the Architecture
 4. **Begin Development**: Start the Core Development Cycle that follows
 
+#### Planning Artifacts (Standard Paths)
+
+```text
+PRD              → docs/prd.md
+Architecture     → docs/architecture.md
+Sharded Epics    → docs/epics/
+Sharded Stories  → docs/stories/
+QA Assessments   → docs/qa/assessments/
+QA Gates         → docs/qa/gates/
+```
+
 ### The Core Development Cycle (IDE)
 
 Once planning is complete and documents are sharded, BMad follows a structured development workflow:
@@ -85,14 +101,22 @@ Once planning is complete and documents are sharded, BMad follows a structured d
 graph TD
     A["Development Phase Start"] --> B["SM: Reviews Previous Story Dev/QA Notes"]
     B --> B2["SM: Drafts Next Story from Sharded Epic + Architecture"]
-    B2 --> B3{"PO: Validate Story Draft (Optional)"}
+    B2 --> S{"High-Risk Story? (Optional)"}
+    S -->|Yes| T["QA: *risk + *design on Draft Story"]
+    S -->|No| B3
+    T --> U["Test Strategy & Risk Profile Created"]
+    U --> B3{"PO: Validate Story Draft (Optional)"}
     B3 -->|Validation Requested| B4["PO: Validate Story Against Artifacts"]
     B3 -->|Skip Validation| C{"User Approval"}
     B4 --> C
     C -->|Approved| D["Dev: Sequential Task Execution"]
     C -->|Needs Changes| B2
     D --> E["Dev: Implement Tasks + Tests"]
-    E --> F["Dev: Run All Validations"]
+    E --> V{"Mid-Dev QA Check? (Optional)"}
+    V -->|Yes| W["QA: *trace or *nfr for Early Validation"]
+    V -->|No| F
+    W --> X["Dev: Address Coverage/NFR Gaps"]
+    X --> F["Dev: Run All Validations"]
     F --> G["Dev: Mark Ready for Review + Add Notes"]
     G --> H{"User Verification"}
     H -->|Request QA Review| I["QA: Test Architect Review + Quality Gate"]
@@ -103,17 +127,26 @@ graph TD
     L -->|Approved| M
     H -->|Needs Fixes| D
     M --> N["IMPORTANT: COMMIT YOUR CHANGES BEFORE PROCEEDING!"]
-    N --> K["Mark Story as Done"]
+    N --> Y{"Gate Update Needed?"}
+    Y -->|Yes| Z["QA: *gate to Update Status"]
+    Y -->|No| K
+    Z --> K["Mark Story as Done"]
     K --> B
 
     style A fill:#f5f5f5,color:#000
     style B fill:#e8f5e9,color:#000
     style B2 fill:#e8f5e9,color:#000
+    style S fill:#e3f2fd,color:#000
+    style T fill:#ffd54f,color:#000
+    style U fill:#ffd54f,color:#000
     style B3 fill:#e3f2fd,color:#000
     style B4 fill:#fce4ec,color:#000
     style C fill:#e3f2fd,color:#000
     style D fill:#e3f2fd,color:#000
     style E fill:#e3f2fd,color:#000
+    style V fill:#e3f2fd,color:#000
+    style W fill:#ffd54f,color:#000
+    style X fill:#e3f2fd,color:#000
     style F fill:#e3f2fd,color:#000
     style G fill:#e3f2fd,color:#000
     style H fill:#e3f2fd,color:#000
@@ -123,13 +156,23 @@ graph TD
     style L fill:#e3f2fd,color:#000
     style M fill:#ff5722,color:#fff
     style N fill:#d32f2f,color:#fff
+    style Y fill:#e3f2fd,color:#000
+    style Z fill:#ffd54f,color:#000
 ```
 
+## Prerequisites
+
+Before installing BMad Method, ensure you have:
+
+- **Node.js** ≥ 18, **npm** ≥ 9
+- **Git** installed and configured
+- **(Optional)** VS Code with "Markdown All in One" + "Markdown Preview Mermaid Support" extensions
+
 ## Installation
 
 ### Optional
 
-If you want to do the planning in the Web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPT's:
+If you want to do the planning on the web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPTs:
 
 1. Navigate to `dist/teams/`
 2. Copy `team-fullstack.txt`
@@ -146,17 +189,17 @@ npx bmad-method install
 
 ## Special Agents
 
-There are two bmad agents - in the future they will be consolidated into the single bmad-master.
+There are two BMad agents — in the future they'll be consolidated into a single BMad-Master.
 
 ### BMad-Master
 
-This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the BMad Method when in the web by accessing the knowledge base and explaining anything to you about the process.
+This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the BMad Method when on the web by accessing the knowledge base and explaining anything to you about the process.
 
 If you don't want to bother switching between different agents aside from the dev, this is the agent for you. Just remember that as the context grows, the performance of the agent degrades, therefore it is important to instruct the agent to compact the conversation and start a new conversation with the compacted conversation as the initial message. Do this often, preferably after each story is implemented.
 
 ### BMad-Orchestrator
 
-This agent should NOT be used within the IDE, it is a heavy weight special purpose agent that utilizes a lot of context and can morph into any other agent. This exists solely to facilitate the team's within the web bundles. If you use a web bundle you will be greeted by the BMad Orchestrator.
+This agent should NOT be used within the IDE, it is a heavyweight, special-purpose agent that utilizes a lot of context and can morph into any other agent. This exists solely to facilitate the teams within the web bundles. If you use a web bundle you will be greeted by the BMad Orchestrator.
 
 ### How Agents Work
 
@@ -187,12 +230,12 @@ dependencies:
 **In IDE:**
 
 ```bash
-# Some Ide's, like Cursor or Windsurf for example, utilize manual rules so interaction is done with the '@' symbol
+# Some IDEs, like Cursor or Windsurf for example, utilize manual rules so interaction is done with the '@' symbol
 @pm Create a PRD for a task management app
 @architect Design the system architecture
 @dev Implement the user authentication
 
-# Some, like Claude Code use slash commands instead
+# Some IDEs, like Claude Code, use slash commands instead
 /pm Create user stories
 /dev Fix the login bug
 ```
@@ -218,20 +261,46 @@ dependencies:
 
 The QA agent in BMad is not just a "senior developer reviewer" - it's a **Test Architect** with deep expertise in test strategy, quality gates, and risk-based testing. Named Quinn, this agent provides advisory authority on quality matters while actively improving code when safe to do so.
 
+#### Quick Start (Essential Commands)
+
+```bash
+@qa *risk {story}       # Assess risks before development
+@qa *design {story}     # Create test strategy
+@qa *trace {story}      # Verify test coverage during dev
+@qa *nfr {story}        # Check quality attributes
+@qa *review {story}     # Full assessment → writes gate
+```
+
+#### Command Aliases (Test Architect)
+
+The documentation uses short forms for convenience. Both styles are valid:
+
+```text
+*risk    → *risk-profile
+*design  → *test-design  
+*nfr     → *nfr-assess
+*trace   → *trace-requirements (or just *trace)
+*review  → *review
+*gate    → *gate
+```
+
 ### Core Capabilities
 
-#### 1. Comprehensive Test Architecture Review
+#### 1. Risk Profiling (`*risk`)
 
-When you run `@qa *review {story}`, Quinn performs:
+**When:** After story draft, before development begins (earliest intervention point)
 
-- **Requirements Traceability**: Maps every acceptance criterion to its validating tests
+Identifies and assesses implementation risks:
-- **Test Level Analysis**: Ensures appropriate testing at unit, integration, and E2E levels
+
-- **Coverage Assessment**: Identifies gaps and redundant test coverage
+- **Categories**: Technical, Security, Performance, Data, Business, Operational
-- **Active Refactoring**: Improves code quality directly when safe
+- **Scoring**: Probability × Impact analysis (1-9 scale)
-- **Quality Gate Decision**: Issues PASS/CONCERNS/FAIL status based on findings
+- **Mitigation**: Specific strategies for each identified risk
+- **Gate Impact**: Risks ≥9 trigger FAIL, ≥6 trigger CONCERNS (see `tasks/risk-profile.md` for authoritative rules)
 
 #### 2. Test Design (`*design`)
 
+**When:** After story draft, before development begins (guides what tests to write)
+
 Creates comprehensive test strategies including:
 
 - Test scenarios for each acceptance criterion
@@ -255,24 +324,9 @@ test_summary:
     P2: 6 # Nice to have - low risks
 ```
 
-#### 3. Risk Profiling (`*risk`)
+#### 3. Requirements Tracing (`*trace`)
 
-Identifies and assesses implementation risks:
+**When:** During development (mid-implementation checkpoint)
-
-- **Categories**: Technical, Security, Performance, Data, Business, Operational
-- **Scoring**: Probability × Impact analysis (1-9 scale)
-- **Mitigation**: Specific strategies for each identified risk
-- **Gate Impact**: Risks ≥9 trigger FAIL, ≥6 trigger CONCERNS
-
-#### 4. NFR Assessment (`*nfr`)
-
-Validates non-functional requirements:
-
-- **Core Four**: Security, Performance, Reliability, Maintainability
-- **Evidence-Based**: Looks for actual implementation proof
-- **Gate Integration**: NFR failures directly impact quality gates
-
-#### 5. Requirements Tracing (`*trace`)
 
 Maps requirements to test coverage:
 
@@ -281,8 +335,32 @@ Maps requirements to test coverage:
 - Identifies coverage gaps with severity ratings
 - Creates traceability matrix for audit purposes
 
+#### 4. NFR Assessment (`*nfr`)
+
+**When:** During development or early review (validate quality attributes)
+
+Validates non-functional requirements:
+
+- **Core Four**: Security, Performance, Reliability, Maintainability
+- **Evidence-Based**: Looks for actual implementation proof
+- **Gate Integration**: NFR failures directly impact quality gates
+
+#### 5. Comprehensive Test Architecture Review (`*review`)
+
+**When:** After development complete, story marked "Ready for Review"
+
+When you run `@qa *review {story}`, Quinn performs:
+
+- **Requirements Traceability**: Maps every acceptance criterion to its validating tests
+- **Test Level Analysis**: Ensures appropriate testing at unit, integration, and E2E levels
+- **Coverage Assessment**: Identifies gaps and redundant test coverage
+- **Active Refactoring**: Improves code quality directly when safe
+- **Quality Gate Decision**: Issues PASS/CONCERNS/FAIL status based on findings
+
 #### 6. Quality Gates (`*gate`)
 
+**When:** After review fixes or when gate status needs updating
+
 Manages quality gate decisions:
 
 - **Deterministic Rules**: Clear criteria for PASS/CONCERNS/FAIL
@@ -290,59 +368,39 @@ Manages quality gate decisions:
 - **Advisory Nature**: Provides recommendations, not blocks
 - **Waiver Support**: Documents accepted risks when needed
 
+**Note:** Gates are advisory; teams choose their quality bar. WAIVED requires reason, approver, and expiry date. See `templates/qa-gate-tmpl.yaml` for schema and `tasks/review-story.md` (gate rules) and `tasks/risk-profile.md` for scoring.
+
 ### Working with the Test Architect
 
-#### Basic Review Flow
+#### Integration with BMad Workflow
 
-1. **Developer completes story** and marks "Ready for Review"
+The Test Architect provides value throughout the entire development lifecycle. Here's when and how to leverage each capability:
-2. **Start new conversation** with QA agent
-3. **Run review**: `@qa *review {story-file}`
-4. **Quinn performs**:
-   - Deep code analysis
-   - Active refactoring where safe
-   - Test coverage validation
-   - Quality gate decision
-5. **Outputs created**:
-   - QA Results section added to story file
-   - Gate file in `docs/qa/gates/{epic}.{story}-{slug}.yml`
 
-#### Advanced Quality Assessments - When to Use
+| **Stage** | **Command** | **When to Use** | **Value** | **Output** |
+|-----------|------------|-----------------|-----------|------------|
+| **Story Drafting** | `*risk` | After SM drafts story | Identify pitfalls early | `docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md` |
+| | `*design` | After risk assessment | Guide dev on test strategy | `docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md` |
+| **Development** | `*trace` | Mid-implementation | Verify test coverage | `docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md` |
+| | `*nfr` | While building features | Catch quality issues early | `docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md` |
+| **Review** | `*review` | Story marked complete | Full quality assessment | QA Results in story + gate file |
+| **Post-Review** | `*gate` | After fixing issues | Update quality decision | Updated `docs/qa/gates/{epic}.{story}-{slug}.yml` |
 
-**AFTER Story Draft (Before Dev Starts):**
+#### Example Commands
 
 ```bash
-# Design test strategy BEFORE implementation
+# Planning Stage - Run these BEFORE development starts
-@qa *design {draft-story}
+@qa *risk {draft-story}     # What could go wrong?
-# Output: docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
+@qa *design {draft-story}   # What tests should we write?
-# Why: Guides developer on what tests to write
 
-# Identify risks EARLY to guide implementation
+# Development Stage - Run these DURING coding
-@qa *risk {draft-story}
+@qa *trace {story}          # Are we testing everything?
-# Output: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+@qa *nfr {story}            # Are we meeting quality standards?
-# Why: Helps developer avoid pitfalls and focus on risk areas
-```
 
-**DURING Development (Mid-Implementation):**
+# Review Stage - Run when development complete
+@qa *review {story}         # Comprehensive assessment + refactoring
 
-```bash
+# Post-Review - Run after addressing issues
-# Validate NFR implementation as you build
+@qa *gate {story}           # Update gate status
-@qa *nfr {in-progress-story}
-# Output: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
-# Why: Catch performance/security issues early
-
-# Check test coverage while developing
-@qa *trace {in-progress-story}
-# Output: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
-# Why: Ensure you're writing the right tests
-```
-
-**AFTER Review (Post-Implementation):**
-
-```bash
-# Update gate decision after fixes
-@qa *gate {reviewed-story}
-# Output: docs/qa/gates/{epic}.{story}-{slug}.yml
-# Why: Document final quality decision
 ```
 
 ### Quality Standards Enforced
@@ -363,55 +421,27 @@ Quinn enforces these test quality principles:
 - **FAIL**: Critical issues that should be addressed (security risks, missing P0 tests)
 - **WAIVED**: Issues acknowledged but explicitly accepted by team
 
-### Integration with Development Flow
+### Special Situations
-
-The Test Architect integrates seamlessly:
-
-1. **Planning Phase**: Can review test strategies early
-2. **Development Phase**: Developer implements with test guidelines in mind
-3. **Review Phase**: Comprehensive quality assessment
-4. **Gate Decision**: Clear go/no-go recommendation
-5. **Documentation**: All findings tracked for audit trail
-
-### Integration with BMad Workflow Stages
-
-#### Stage 1: Story Drafting (SM Creates Story)
-
-**Optional but Valuable:**
-
-- Run `*design` on draft → Give to Dev as test requirements
-- Run `*risk` on draft → Highlight concerns for Dev to address
-
-#### Stage 2: Development (Dev Implements)
-
-**Mid-Development Checkpoints:**
-
-- Dev can run `*trace` → Verify tests are being created
-- Dev can run `*nfr` → Check performance/security early
-
-#### Stage 3: Review (Story Ready)
-
-**Standard Review:**
-
-- Run `*review` → Complete assessment + gate decision
-
-**If Issues Found:**
-
-- After fixes, run `*gate` → Update gate status
-
-#### Special Situations
 
 **High-Risk Stories:**
 
-- Always run `*risk` and `*design` before development
+- Always run `*risk` and `*design` before development starts
+- Consider mid-development `*trace` and `*nfr` checkpoints
 
 **Complex Integrations:**
 
-- Run `*trace` to ensure all integration points tested
+- Run `*trace` during development to ensure all integration points tested
+- Follow up with `*nfr` to validate performance across integrations
 
 **Performance-Critical:**
 
-- Run `*nfr` during development, not just at review
+- Run `*nfr` early and often during development
+- Don't wait until review to discover performance issues
+
+**Brownfield/Legacy Code:**
+
+- Start with `*risk` to identify regression dangers
+- Use `*review` with extra focus on backward compatibility
 
 ### Best Practices
 
@@ -422,6 +452,19 @@ The Test Architect integrates seamlessly:
 - **Continuous Learning**: QA documents patterns for team knowledge sharing
 - **Brownfield Care**: Pay extra attention to regression risks in existing systems
 
+### Output Paths Reference
+
+Quick reference for where Test Architect outputs are stored:
+
+```text
+*risk-profile  → docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
+*test-design   → docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
+*trace         → docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
+*nfr-assess    → docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
+*review        → QA Results section in story + gate file reference
+*gate          → docs/qa/gates/{epic}.{story}-{slug}.yml
+```
+
 ## Technical Preferences System
 
 BMad includes a personalization system through the `technical-preferences.md` file located in `.bmad-core/data/` - this can help bias the PM and Architect to recommend your preferences for design patterns, technology selection, or anything else you would like to put in here.
@@ -445,9 +488,9 @@ devLoadAlwaysFiles:
   - docs/architecture/project-structure.md
 ```
 
-You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into it's context. These are the rules the agent will follow.
+You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into its context. These are the rules the agent will follow.
 
-As your project grows and the code starts to build consistent patterns, coding standards should be reduced to include only the standards that the agent still makes with. The agent will look at surrounding code in files to infer the coding standards that are relevant to the current task.
+As your project grows and the code starts to build consistent patterns, coding standards should be reduced to include only the standards the agent still needs enforced. The agent will look at surrounding code in files to infer the coding standards that are relevant to the current task.
 
 ## Getting Help
 

docs/working-in-the-brownfield.md

@@ -76,7 +76,7 @@ The PM will:
 *document-project
 ```
 
-The analyst will:
+The architect will:
 
 - **Ask about your focus** if no PRD was provided
 - **Offer options**: Create PRD, provide requirements, or describe the enhancement
@@ -85,11 +85,11 @@ The analyst will:
 - **Skip unrelated areas** to keep docs lean
 - **Generate ONE architecture document** for all environments
 
-The analyst creates:
+The architect creates:
 
 - **One comprehensive architecture document** following fullstack-architecture template
 - **Covers all system aspects** in a single file
-- **Easy to copy and save** as `docs/project-architecture.md`
+- **Easy to copy and save** as `docs/architecture.md`
 - **Can be sharded later** in IDE if desired
 
 For example, if you say "Add payment processing to user service":
@@ -108,10 +108,10 @@ For example, if you say "Add payment processing to user service":
 2. **Upload your project**:
    - **Option A**: Paste your GitHub repository URL directly
    - **Option B**: Upload your flattened-codebase.xml file
-3. **Load the analyst agent**: Upload `dist/agents/architect.txt`
+3. **Load the architect agent**: Upload `dist/agents/architect.txt`
 4. **Run documentation**: Type `*document-project`
 
-The analyst will generate comprehensive documentation of everything.
+The architect will generate comprehensive documentation of everything.
 
 #### Phase 2: Plan Your Enhancement
 
@@ -206,19 +206,20 @@ The PO ensures:
 ### Phase 4: Save and Shard Documents
 
 1. Save your PRD and Architecture as:
-   docs/brownfield-prd.md
+   docs/prd.md
-   docs/brownfield-architecture.md
+   docs/architecture.md
+   (Note: You can optionally prefix with 'brownfield-' if managing multiple versions)
 2. Shard your docs:
    In your IDE
 
    ```bash
    @po
-   shard docs/brownfield-prd.md
+   shard docs/prd.md
    ```
 
    ```bash
    @po
-   shard docs/brownfield-architecture.md
+   shard docs/architecture.md
    ```
 
 ### Phase 5: Transition to Development
@@ -255,74 +256,172 @@ Brownfield changes should:
 
 ### 4. Test Integration with the Test Architect
 
+#### Why the Test Architect is Critical for Brownfield
+
+In brownfield projects, the Test Architect (Quinn) becomes your safety net against breaking existing functionality. Unlike greenfield where you're building fresh, brownfield requires careful validation that new changes don't destabilize what already works.
+
 #### Brownfield-Specific Testing Challenges
 
-The Test Architect (QA agent) is especially valuable in brownfield projects for:
+The Test Architect addresses unique brownfield complexities:
 
-- **Regression Risk Assessment**: Identifying which existing tests might break
+| **Challenge** | **How Test Architect Helps** | **Command** |
-- **Integration Test Design**: Ensuring new code works with legacy systems
+|--------------|------------------------------|-------------|
-- **Coverage Gap Analysis**: Finding untested legacy code paths
+| **Regression Risks** | Identifies which existing features might break | `*risk` |
-- **Performance Impact**: Validating no degradation to existing functionality
+| **Legacy Dependencies** | Maps integration points and hidden dependencies | `*trace` |
+| **Performance Degradation** | Validates no slowdown in existing flows | `*nfr` |
+| **Coverage Gaps** | Finds untested legacy code that new changes touch | `*design` |
+| **Breaking Changes** | Detects API/contract violations | `*review` |
+| **Migration Safety** | Validates data transformations and rollback plans | `*risk` + `*review` |
 
-#### Test Architect Workflow Stages for Brownfield
+#### Complete Test Architect Workflow for Brownfield
 
-##### Stage 1: After Story Creation (Critical for Brownfield)
+##### Stage 1: Before Development (Risk & Strategy)
 
-**HIGHLY RECOMMENDED - Identify Integration Risks Early:**
+**CRITICAL FOR BROWNFIELD - Run These First:**
 
 ```bash
-# Assess integration risks BEFORE coding
+# 1. RISK ASSESSMENT (Run IMMEDIATELY after story creation)
 @qa *risk {brownfield-story}
+# Identifies: Legacy dependencies, breaking changes, integration points
 # Output: docs/qa/assessments/{epic}.{story}-risk-{YYYYMMDD}.md
-# Why: Identifies legacy dependencies, breaking changes, integration risks
+# Brownfield Focus: 
+#   - Regression probability scoring
+#   - Affected downstream systems
+#   - Data migration risks
+#   - Rollback complexity
 
-# Design regression-aware test strategy
+# 2. TEST DESIGN (After risk assessment)
-@qa *design {brownfield-story}
+@qa *design {brownfield-story}  
+# Creates: Regression test strategy + new feature tests
 # Output: docs/qa/assessments/{epic}.{story}-test-design-{YYYYMMDD}.md
-# Why: Plans tests for both new features AND regression prevention
+# Brownfield Focus:
+#   - Existing functionality that needs regression tests
+#   - Integration test requirements
+#   - Performance benchmarks to maintain
+#   - Feature flag test scenarios
 ```
 
-##### Stage 2: During Development (Monitor Integration)
+##### Stage 2: During Development (Continuous Validation)
 
-**Dev Should Check Compatibility:**
+**Monitor Integration Health While Coding:**
 
 ```bash
-# Trace requirements to preserve existing functionality
+# 3. REQUIREMENTS TRACING (Mid-development checkpoint)
 @qa *trace {brownfield-story}
+# Maps: New requirements + existing functionality preservation
 # Output: docs/qa/assessments/{epic}.{story}-trace-{YYYYMMDD}.md
-# Why: Maps new requirements AND existing functionality that must work
+# Brownfield Focus:
+#   - Existing features that must still work
+#   - New/old feature interactions
+#   - API contract preservation
+#   - Missing regression test coverage
 
-# Validate performance hasn't degraded
+# 4. NFR VALIDATION (Before considering "done")
 @qa *nfr {brownfield-story}
+# Validates: Performance, security, reliability unchanged
 # Output: docs/qa/assessments/{epic}.{story}-nfr-{YYYYMMDD}.md
-# Why: Catch performance regressions early
+# Brownfield Focus:
+#   - Performance regression detection
+#   - Security implications of integrations
+#   - Backward compatibility validation
+#   - Load/stress on legacy components
 ```
 
-##### Stage 3: Review (Deep Integration Analysis)
+##### Stage 3: Code Review (Deep Integration Analysis)
 
-**Standard Review with Brownfield Focus:**
+**Comprehensive Brownfield Review:**
 
 ```bash
+# 5. FULL REVIEW (When development complete)
 @qa *review {brownfield-story}
+# Performs: Deep analysis + active refactoring
+# Outputs: 
+#   - QA Results in story file
+#   - Gate file: docs/qa/gates/{epic}.{story}-{slug}.yml
 ```
 
-Performs deep analysis with special attention to:
+The review specifically analyzes:
 
-- Breaking changes to existing APIs
+- **API Breaking Changes**: Validates all existing contracts maintained
-- Data migration correctness
+- **Data Migration Safety**: Checks transformation logic and rollback procedures
-- Performance regression
+- **Performance Regression**: Compares against baseline metrics
-- Security implications of integrations
+- **Integration Points**: Validates all touchpoints with legacy code
-- Backwards compatibility
+- **Feature Flag Logic**: Ensures proper toggle behavior
-- Feature flag correctness
+- **Dependency Impacts**: Maps affected downstream systems
 
-#### Focus Areas for Brownfield Testing
+##### Stage 4: Post-Review (Gate Updates)
 
-- **Integration Points**: Test all integration points with existing code
+```bash
-- **Existing Functionality**: Comprehensive regression testing
+# 6. GATE STATUS UPDATE (After addressing issues)
-- **Performance Impact**: Benchmark against current performance
+@qa *gate {brownfield-story}
-- **Data Migrations**: Validate data integrity and rollback procedures
+# Updates: Quality gate decision after fixes
-- **Backwards Compatibility**: Ensure existing clients still work
+# Output: docs/qa/gates/{epic}.{story}-{slug}.yml
-- **Feature Flags**: Test both enabled and disabled states
+# Brownfield Considerations:
+#   - May WAIVE certain legacy code issues
+#   - Documents technical debt acceptance
+#   - Tracks migration progress
+```
+
+#### Brownfield-Specific Risk Scoring
+
+The Test Architect uses enhanced risk scoring for brownfield:
+
+| **Risk Category** | **Brownfield Factors** | **Impact on Gate** |
+|------------------|------------------------|-------------------|
+| **Regression Risk** | Number of integration points × Age of code | Score ≥9 = FAIL |
+| **Data Risk** | Migration complexity × Data volume | Score ≥6 = CONCERNS |
+| **Performance Risk** | Current load × Added complexity | Score ≥6 = CONCERNS |
+| **Compatibility Risk** | API consumers × Contract changes | Score ≥9 = FAIL |
+
+#### Brownfield Testing Standards
+
+Quinn enforces additional standards for brownfield:
+
+- **Regression Test Coverage**: Every touched legacy module needs tests
+- **Performance Baselines**: Must maintain or improve current metrics
+- **Rollback Procedures**: Every change needs a rollback plan
+- **Feature Flags**: All risky changes behind toggles
+- **Integration Tests**: Cover all legacy touchpoints
+- **Contract Tests**: Validate API compatibility
+- **Data Validation**: Migration correctness checks
+
+#### Quick Reference: Brownfield Test Commands
+
+| **Scenario** | **Commands to Run** | **Order** | **Why Critical** |
+|-------------|-------------------|-----------|------------------|
+| **Adding Feature to Legacy Code** | `*risk` → `*design` → `*trace` → `*review` | Sequential | Map all dependencies first |
+| **API Modification** | `*risk` → `*design` → `*nfr` → `*review` | Sequential | Prevent breaking consumers |
+| **Performance-Critical Change** | `*nfr` early and often → `*review` | Continuous | Catch degradation immediately |
+| **Data Migration** | `*risk` → `*design` → `*trace` → `*review` → `*gate` | Full cycle | Ensure data integrity |
+| **Bug Fix in Complex System** | `*risk` → `*trace` → `*review` | Focused | Prevent side effects |
+
+#### Integration with Brownfield Scenarios
+
+**Scenario-Specific Guidance:**
+
+1. **Legacy Code Modernization**
+   - Start with `*risk` to map all dependencies
+   - Use `*design` to plan strangler fig approach
+   - Run `*trace` frequently to ensure nothing breaks
+   - `*review` with focus on gradual migration
+
+2. **Adding Features to Monolith**
+   - `*risk` identifies integration complexity
+   - `*design` plans isolation strategies
+   - `*nfr` monitors performance impact
+   - `*review` validates no monolith degradation
+
+3. **Microservice Extraction**
+   - `*risk` maps service boundaries
+   - `*trace` ensures functionality preservation
+   - `*nfr` validates network overhead acceptable
+   - `*gate` documents accepted trade-offs
+
+4. **Database Schema Changes**
+   - `*risk` assesses migration complexity
+   - `*design` plans backward-compatible approach
+   - `*trace` maps all affected queries
+   - `*review` validates migration safety
 
 ### 5. Communicate Changes
 
@@ -339,32 +438,63 @@ Document:
 
 1. Document existing system
 2. Create brownfield PRD focusing on integration
-3. Architecture emphasizes compatibility
+3. **Test Architect Early Involvement**:
-4. Stories include integration tasks
+   - Run `@qa *risk` on draft stories to identify integration risks
+   - Use `@qa *design` to plan regression test strategy
+4. Architecture emphasizes compatibility
+5. Stories include integration tasks with test requirements
+6. **During Development**:
+   - Developer runs `@qa *trace` to verify coverage
+   - Use `@qa *nfr` to monitor performance impact
+7. **Review Stage**: `@qa *review` validates integration safety
 
 ### Scenario 2: Modernizing Legacy Code
 
 1. Extensive documentation phase
 2. PRD includes migration strategy
-3. Architecture plans gradual transition
+3. **Test Architect Strategy Planning**:
-4. Stories follow strangler fig pattern
+   - `@qa *risk` assesses modernization complexity
+   - `@qa *design` plans parallel testing approach
+4. Architecture plans gradual transition (strangler fig pattern)
+5. Stories follow incremental modernization with:
+   - Regression tests for untouched legacy code
+   - Integration tests for new/old boundaries
+   - Performance benchmarks at each stage
+6. **Continuous Validation**: Run `@qa *trace` after each increment
+7. **Gate Management**: Use `@qa *gate` to track technical debt acceptance
 
 ### Scenario 3: Bug Fix in Complex System
 
 1. Document relevant subsystems
 2. Use `create-brownfield-story` for focused fix
-3. Include regression test requirements
+3. **Test Architect Risk Assessment**: Run `@qa *risk` to identify side effect potential
-4. Test Architect validates no side effects using:
+4. Include regression test requirements from `@qa *design` output
-   - Risk profiling for side effect analysis
+5. **During Fix**: Use `@qa *trace` to map affected functionality
+6. **Before Commit**: Run `@qa *review` for comprehensive validation
+7. Test Architect validates no side effects using:
+   - Risk profiling for side effect analysis (probability × impact scoring)
    - Trace matrix to ensure fix doesn't break related features
    - NFR assessment to verify performance/security unchanged
+   - Gate decision documents fix safety
 
 ### Scenario 4: API Integration
 
 1. Document existing API patterns
 2. PRD defines integration requirements
-3. Architecture ensures consistent patterns
+3. **Test Architect Contract Analysis**:
-4. Stories include API documentation updates
+   - `@qa *risk` identifies breaking change potential
+   - `@qa *design` creates contract test strategy
+4. Architecture ensures consistent patterns
+5. **API Testing Focus**:
+   - Contract tests for backward compatibility
+   - Integration tests for new endpoints
+   - Performance tests for added load
+6. Stories include API documentation updates
+7. **Validation Checkpoints**:
+   - `@qa *trace` maps all API consumers
+   - `@qa *nfr` validates response times
+   - `@qa *review` ensures no breaking changes
+8. **Gate Decision**: Document any accepted breaking changes with migration path
 
 ## Troubleshooting
 
@@ -390,19 +520,37 @@ Document:
 
 ```bash
 # Document existing project
-@architect → *document-project
+@architect *document-project
 
 # Create enhancement PRD
-@pm → *create-brownfield-prd
+@pm *create-brownfield-prd
 
 # Create architecture with integration focus
-@architect → *create-brownfield-architecture
+@architect *create-brownfield-architecture
 
 # Quick epic creation
-@pm → *create-brownfield-epic
+@pm *create-brownfield-epic
 
 # Single story creation
-@pm → *create-brownfield-story
+@pm *create-brownfield-story
+```
+
+### Test Architect Commands for Brownfield
+
+Note: Short forms shown below. Full commands: `*risk-profile`, `*test-design`, `*nfr-assess`, `*trace-requirements`
+
+```bash
+# BEFORE DEVELOPMENT (Planning)
+@qa *risk {story}     # Assess regression & integration risks
+@qa *design {story}   # Plan regression + new feature tests
+
+# DURING DEVELOPMENT (Validation)
+@qa *trace {story}    # Verify coverage of old + new
+@qa *nfr {story}      # Check performance degradation
+
+# AFTER DEVELOPMENT (Review)
+@qa *review {story}   # Deep integration analysis
+@qa *gate {story}     # Update quality decision
 ```
 
 ### Decision Tree
@@ -417,13 +565,33 @@ Do you have a large codebase or monorepo?
 
 Is this a major enhancement affecting multiple systems?
 ├─ Yes → Full Brownfield Workflow
+│   └─ ALWAYS run Test Architect *risk + *design first
 └─ No → Is this more than a simple bug fix?
-    ├─ Yes → brownfield-create-epic
+    ├─ Yes → *create-brownfield-epic
-    └─ No → brownfield-create-story
+    │   └─ Run Test Architect *risk for integration points
+    └─ No → *create-brownfield-story
+        └─ Still run *risk if touching critical paths
+
+Does the change touch legacy code?
+├─ Yes → Test Architect is MANDATORY
+│   ├─ *risk → Identify regression potential
+│   ├─ *design → Plan test coverage
+│   └─ *review → Validate no breakage
+└─ No → Test Architect is RECOMMENDED
+    └─ *review → Ensure quality standards
 ```
 
 ## Conclusion
 
-Brownfield development with BMad-Method provides structure and safety when modifying existing systems. The key is providing comprehensive context through documentation, using specialized templates that consider integration requirements, and following workflows that respect existing constraints while enabling progress.
+Brownfield development with BMad Method provides structure and safety when modifying existing systems. The Test Architect becomes your critical safety net, using risk assessment, regression testing, and continuous validation to ensure new changes don't destabilize existing functionality.
 
-Remember: **Document First, Plan Carefully, Integrate Safely**
+**The Brownfield Success Formula:**
+
+1. **Document First** - Understand what exists
+2. **Assess Risk Early** - Use Test Architect `*risk` before coding
+3. **Plan Test Strategy** - Design regression + new feature tests
+4. **Validate Continuously** - Check integration health during development
+5. **Review Comprehensively** - Deep analysis before committing
+6. **Gate Decisively** - Document quality decisions
+
+Remember: **In brownfield, the Test Architect isn't optional - it's your insurance policy against breaking production.**