BMAD-METHOD/src/modules/bmm/workflows/testarch/trace/README.md

Requirements Traceability Workflow

Workflow ID: testarch-trace Agent: Test Architect (TEA) Command: bmad tea *trace

---

Overview

The trace workflow generates a comprehensive requirements-to-tests traceability matrix that maps acceptance criteria to implemented tests, identifies coverage gaps, and provides actionable recommendations for improving test coverage.

Key Features:

• Maps acceptance criteria to specific test cases across all levels (E2E, API, Component, Unit)
• Classifies coverage status (FULL, PARTIAL, NONE, UNIT-ONLY, INTEGRATION-ONLY)
• Prioritizes gaps by risk level (P0/P1/P2/P3)
• Generates CI/CD-ready YAML snippets for quality gates
• Detects duplicate coverage across test levels
• Verifies test quality (assertions, structure, performance)

---

When to Use This Workflow

Use *trace when you need to:

• ✅ Validate that all acceptance criteria have test coverage
• ✅ Identify coverage gaps before release or PR merge
• ✅ Generate traceability documentation for compliance or audits
• ✅ Ensure critical paths (P0/P1) are fully tested
• ✅ Detect duplicate coverage across test levels
• ✅ Assess test quality across your suite
• ✅ Create gate-ready metrics for CI/CD pipelines

Typical Timing:

• After tests are implemented (post-ATDD or post-development)
• Before merging a PR (validate P0/P1 coverage)
• Before release (validate full coverage)
• During sprint retrospectives (assess test quality)

---

Prerequisites

Required:

• Acceptance criteria (from story file OR inline)
• Implemented test suite (or acknowledged gaps)

Recommended:

• test-design.md - Risk assessment and test priorities
• tech-spec.md - Technical implementation details
• Test framework configuration (playwright.config.ts, jest.config.js)

Halt Conditions:

• Story lacks any tests AND gaps are not acknowledged → Run *atdd first
• Acceptance criteria are completely missing → Provide criteria or story file

---

Usage

Basic Usage (BMad Mode)

bmad tea *trace

The workflow will:

1. Read story file from bmad/output/story-X.X.md
2. Extract acceptance criteria
3. Auto-discover tests for this story
4. Generate traceability matrix
5. Save to bmad/output/traceability-matrix.md

Standalone Mode (No Story File)

bmad tea *trace --acceptance-criteria "AC-1: User can login with email..."

Custom Configuration

bmad tea *trace \
  --story-file "bmad/output/story-1.3.md" \
  --output-file "docs/qa/trace-1.3.md" \
  --min-p0-coverage 100 \
  --min-p1-coverage 90

---

Workflow Steps

1. Load Context - Read story, test design, tech spec, knowledge base
2. Discover Tests - Auto-find tests related to story (by ID, describe blocks, file paths)
3. Map Criteria - Link acceptance criteria to specific test cases
4. Analyze Gaps - Identify missing coverage and prioritize by risk
5. Verify Quality - Check test quality (assertions, structure, performance)
6. Generate Deliverables - Create traceability matrix, gate YAML, coverage badge

---

Outputs

Traceability Matrix (traceability-matrix.md)

Comprehensive markdown file with:

• Coverage summary table (by priority)
• Detailed criterion-to-test mapping
• Gap analysis with recommendations
• Quality assessment for each test
• Gate YAML snippet

Gate YAML Snippet

traceability:
  story_id: '1.3'
  coverage:
    overall: 85%
    p0: 100%
    p1: 90%
  gaps:
    critical: 0
    high: 1
  status: 'PASS'

Updated Story File (Optional)

Adds "Traceability" section to story markdown with:

• Link to traceability matrix
• Coverage summary
• Gate status

---

Coverage Classifications

• FULL ✅ - All scenarios validated at appropriate level(s)
• PARTIAL ⚠️ - Some coverage but missing edge cases or levels
• NONE ❌ - No test coverage at any level
• UNIT-ONLY ⚠️ - Only unit tests (missing integration/E2E validation)
• INTEGRATION-ONLY ⚠️ - Only API/Component tests (missing unit confidence)

---

Quality Gates

Priority	Coverage Requirement	Severity	Action
P0	100%	BLOCKER	Do not release
P1	90%	HIGH	Block PR merge
P2	80% (recommended)	MEDIUM	Address in nightly
P3	No requirement	LOW	Optional

---

Configuration

workflow.yaml Variables

variables:
  # Target specification
  story_file: '' # Path to story markdown
  acceptance_criteria: '' # Inline criteria if no story

  # Test discovery
  test_dir: '{project-root}/tests'
  auto_discover_tests: true

  # Traceability configuration
  coverage_levels: 'e2e,api,component,unit'
  map_by_test_id: true
  map_by_describe: true
  map_by_filename: true

  # Gap analysis
  prioritize_by_risk: true
  suggest_missing_tests: true
  check_duplicate_coverage: true

  # Output configuration
  output_file: '{output_folder}/traceability-matrix.md'
  generate_gate_yaml: true
  generate_coverage_badge: true
  update_story_file: true

  # Quality gates
  min_p0_coverage: 100
  min_p1_coverage: 90
  min_overall_coverage: 80

---

Knowledge Base Integration

This workflow automatically loads relevant knowledge fragments:

• traceability.md - Requirements mapping patterns
• test-priorities.md - P0/P1/P2/P3 risk framework
• risk-governance.md - Risk-based testing approach
• test-quality.md - Definition of Done for tests
• selective-testing.md - Duplicate coverage patterns

---

Examples

Example 1: Full Coverage Validation

# Validate P0/P1 coverage before PR merge
bmad tea *trace --story-file "bmad/output/story-1.3.md"

Output:

# Traceability Matrix - Story 1.3

## Coverage Summary

| Priority | Total | FULL | Coverage % | Status  |
| -------- | ----- | ---- | ---------- | ------- |
| P0       | 3     | 3    | 100%       | ✅ PASS |
| P1       | 5     | 5    | 100%       | ✅ PASS |

Gate Status: PASS ✅

Example 2: Gap Identification

# Find coverage gaps for existing feature
bmad tea *trace --target-feature "user-authentication"

Output:

## Gap Analysis

### Critical Gaps (BLOCKER)

- None ✅

### High Priority Gaps (PR BLOCKER)

1. **AC-3: Password reset email edge cases**
   - Recommend: Add 1.3-API-001 (email service integration)
   - Impact: Users may not recover accounts in error scenarios

Example 3: Duplicate Coverage Detection

# Check for redundant tests
bmad tea *trace --check-duplicate-coverage true

Output:

## Duplicate Coverage Detected

⚠️ AC-1 (login validation) is tested at multiple levels:

- 1.3-E2E-001 (full user journey) ✅ Appropriate
- 1.3-UNIT-001 (business logic) ✅ Appropriate
- 1.3-COMPONENT-001 (form validation) ⚠️ Redundant with UNIT-001

Recommendation: Remove 1.3-COMPONENT-001 or consolidate with UNIT-001

---

Troubleshooting

"No tests found for this story"

• Run *atdd workflow first to generate failing acceptance tests
• Check test file naming conventions (may not match story ID pattern)
• Verify test directory path is correct (test_dir variable)

"Cannot determine coverage status"

• Tests may lack explicit mapping (no test IDs, unclear describe blocks)
• Add test IDs: {STORY_ID}-{LEVEL}-{SEQ} (e.g., 1.3-E2E-001)
• Use Given-When-Then narrative in test descriptions

"P0 coverage below 100%"

• This is a BLOCKER - do not release
• Identify missing P0 tests in gap analysis
• Run *atdd workflow to generate missing tests
• Verify P0 classification is correct with stakeholders

"Duplicate coverage detected"

• Review selective-testing.md knowledge fragment
• Determine if overlap is acceptable (defense in depth) or wasteful
• Consolidate tests at appropriate level (logic → unit, journey → E2E)

---

Integration with Other Workflows

• testarch-test-design → *trace - Define priorities, then trace coverage
• testarch-atdd → *trace - Generate tests, then validate coverage
• *trace → testarch-automate - Identify gaps, then automate regression
• *trace → testarch-gate - Generate metrics, then apply quality gates
• *trace → testarch-test-review - Flag quality issues, then review tests

---

Best Practices

1. Run Trace After Test Implementation

   • Don't run *trace before tests exist (run *atdd first)
   • Trace is most valuable after initial test suite is written

2. Prioritize by Risk

   • P0 gaps are BLOCKERS (must fix before release)
   • P1 gaps are HIGH priority (block PR merge)
   • P3 gaps are acceptable (fix if time permits)

3. Explicit Mapping

   • Use test IDs (1.3-E2E-001) for clear traceability
   • Reference criteria in describe blocks
   • Use Given-When-Then narrative

4. Avoid Duplicate Coverage

   • Test each behavior at appropriate level only
   • Unit tests for logic, E2E for journeys
   • Only overlap for defense in depth on critical paths

5. Generate Gate-Ready Artifacts

   • Enable generate_gate_yaml for CI/CD integration
   • Use YAML snippets in pipeline quality gates
   • Export metrics for dashboard visualization

---

Related Commands

• bmad tea *test-design - Define test priorities and risk assessment
• bmad tea *atdd - Generate failing acceptance tests for gaps
• bmad tea *automate - Expand regression suite based on gaps
• bmad tea *gate - Apply quality gates using traceability metrics
• bmad tea *test-review - Review test quality issues flagged by trace

---

Resources

• Instructions - Detailed workflow steps
• Checklist - Validation checklist
• Template - Traceability matrix template
• Knowledge Base - Testing best practices

---