ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/.claude/tasks/analysis/trace-requirements.md

9.2 KiB
Raw Blame History

Requirements Traceability Task

Purpose

Establish and maintain comprehensive traceability between business requirements, user stories, technical specifications, test cases, and implementation artifacts. Ensure all requirements are properly addressed and validated throughout the development lifecycle.

Traceability Framework

Traceability Levels

Level 1: Business Requirements → User Stories

  • Map high-level business objectives to specific user stories
  • Ensure complete coverage of business needs
  • Identify gaps in requirement coverage

Level 2: User Stories → Technical Specifications

  • Link user stories to system architecture components
  • Map functional requirements to technical implementation
  • Trace non-functional requirements to system design

Level 3: Technical Specifications → Implementation

  • Connect architectural decisions to code components
  • Map API specifications to actual endpoints
  • Trace database design to data models

Level 4: Implementation → Test Cases

  • Link code components to unit tests
  • Map user stories to acceptance tests
  • Trace technical specifications to integration tests

Level 5: Test Cases → Validation Results

  • Connect test execution to requirement verification
  • Map test results to acceptance criteria satisfaction
  • Trace quality metrics to business objectives

Traceability Matrix Structure

Forward Traceability (Requirements → Implementation)

Requirement ID Description User Story Tech Spec Implementation Test Case Status
BUS-001 User authentication US-001, US-002 ARCH-001 auth.service.ts TC-001-005 ✅
BUS-002 Data export US-003 ARCH-002 export.service.ts TC-006-008 ⚠️

Backward Traceability (Implementation → Requirements)

Implementation Technical Spec User Story Business Requirement Rationale
payment.service.ts ARCH-003 US-004 BUS-003 Payment processing
user.model.ts ARCH-001 US-001, US-002 BUS-001 User management

Task Execution Process

1. Requirements Collection and Categorization

Business Requirements (BUS-):

  • High-level business objectives and goals
  • Stakeholder needs and constraints
  • Success criteria and KPIs
  • Regulatory and compliance requirements

Functional Requirements (FUNC-):

  • Specific system capabilities and features
  • User interaction and workflow requirements
  • Data processing and business logic needs
  • Integration and interface requirements

Non-Functional Requirements (NFR-):

  • Performance, scalability, and reliability requirements
  • Security, privacy, and compliance needs
  • Usability, accessibility, and user experience standards
  • Maintainability, portability, and operational requirements

2. User Story Mapping

Story Identification:

Epic: User Authentication (BUS-001)
├── US-001: User Registration
│   ├── Given: New user wants to create account
│   ├── When: They provide valid registration information  
│   └── Then: Account is created and confirmed
├── US-002: User Login
│   ├── Given: Registered user wants to access system
│   ├── When: They provide valid credentials
│   └── Then: They are authenticated and redirected

Acceptance Criteria Traceability:

  • Map each acceptance criterion to specific test cases
  • Link business rules to validation logic
  • Trace user interactions to UI components

3. Technical Specification Mapping

Architecture Traceability:

business_requirement: BUS-001 (User Authentication)
user_stories: [US-001, US-002]
technical_components:
  - component: AuthenticationService
    responsibility: "Handle user login/logout"
    requirements: [FUNC-001, FUNC-002]
    tests: [TC-001, TC-002, TC-003]
  - component: UserRepository  
    responsibility: "Manage user data persistence"
    requirements: [FUNC-001, NFR-001]
    tests: [TC-004, TC-005]

API Specification Traceability:

  • Map user stories to API endpoints
  • Link business rules to API validation
  • Trace data requirements to API schemas

4. Implementation Traceability

Code Component Mapping:

/**
 * @requirements BUS-001, FUNC-001, FUNC-002
 * @user_stories US-001, US-002  
 * @test_cases TC-001, TC-002, TC-003
 */
class AuthenticationService {
  // Implementation traces back to specific requirements
}

Database Schema Traceability:

  • Map data entities to business requirements
  • Link schema changes to requirement evolution
  • Trace performance requirements to indexing strategy

5. Test Case Traceability

Test Coverage Analysis:

Feature: User Authentication (BUS-001)
  @requirement:US-001 @test-case:TC-001
  Scenario: Successful user registration
    Given a new user provides valid information
    When they submit the registration form  
    Then their account is created
    And they receive a confirmation email

Test Type Mapping:

  • Unit Tests: Trace to functional requirements and code components
  • Integration Tests: Map to system interface requirements
  • End-to-End Tests: Link to user stories and business workflows
  • Performance Tests: Connect to non-functional requirements

Traceability Analysis and Reporting

Coverage Analysis

Requirement Coverage Report:

## Requirements Coverage Summary

### Business Requirements: 15/15 (100%)
- ✅ All business requirements mapped to user stories
- ✅ All user stories have acceptance criteria
- ✅ All acceptance criteria have test cases

### Technical Specifications: 12/15 (80%)
- ✅ 12 specifications implemented
- ⚠️ 2 specifications partially implemented  
- ❌ 1 specification not implemented

### Test Coverage: 45/50 (90%)
- ✅ Unit tests: 95% coverage
- ✅ Integration tests: 100% of APIs
- ⚠️ E2E tests: 85% of user journeys

Gap Analysis

Missing Traceability:

  • Requirements without corresponding user stories
  • User stories without technical specifications
  • Implementation without test coverage
  • Test cases without requirement justification

Orphaned Artifacts:

  • Code components not traced to requirements
  • Test cases not linked to user stories
  • Technical specifications without implementation
  • Documentation without requirement basis

Impact Analysis

Requirement Changes:

  • Identify all affected artifacts when requirements change
  • Assess implementation and test impacts
  • Plan migration strategy for requirement evolution

Implementation Changes:

  • Trace code changes back to requirement justification
  • Validate that changes align with business needs
  • Ensure test coverage remains adequate

Quality Metrics

Traceability Completeness

  • Forward Traceability: % of requirements traced to implementation
  • Backward Traceability: % of implementation traced to requirements
  • Test Coverage: % of requirements validated by tests
  • Documentation Alignment: % of specs aligned with implementation

Traceability Quality

  • Link Accuracy: Correctness of traceability relationships
  • Update Frequency: How current the traceability matrix is
  • Granularity Appropriateness: Right level of detail for traceability
  • Stakeholder Usability: How well traceability serves different roles

Output Formats

Executive Dashboard

# Requirements Traceability Dashboard

## Overall Health: 92% ✅

### Coverage Metrics
- Business Requirements Coverage: 100% (15/15)
- Implementation Coverage: 95% (48/50 components)  
- Test Coverage: 90% (45/50 test scenarios)
- Documentation Alignment: 88% (current)

### Key Risks
- 2 high-priority requirements partially implemented
- 5 test gaps in critical user journeys
- 3 orphaned code components need requirement justification

Detailed Traceability Matrix

Requirement_ID,Type,Description,User_Story,Tech_Spec,Implementation,Test_Cases,Status,Notes
BUS-001,Business,User Authentication,US-001;US-002,ARCH-001,auth.service.ts,TC-001-005,Complete,
FUNC-001,Functional,Password Validation,US-001,ARCH-001,password.validator.ts,TC-001;TC-002,Complete,
NFR-001,Non-Functional,Response Time < 2s,US-001;US-002,PERF-001,auth.service.ts,TC-020-025,In Progress,Load testing needed

Integration with Other Tasks

Story Review Integration:

  • Validate that new stories trace to business requirements
  • Ensure acceptance criteria are testable and traceable
  • Check for requirement coverage gaps

Quality Gate Integration:

  • Traceability completeness as quality gate criteria
  • Requirement coverage threshold enforcement
  • Impact analysis for requirement changes

Test Design Integration:

  • Use traceability matrix to identify test priorities
  • Ensure high-risk requirements have comprehensive test coverage
  • Validate test scenarios against requirement specifications

Success Criteria

  • Complete Coverage: All requirements traced through to validation
  • Current Information: Traceability matrix updated with each change
  • Decision Support: Traceability enables informed change management
  • Quality Assurance: No requirements slip through without proper validation
  • Audit Readiness: Full requirement satisfaction can be demonstrated