requirement-traceability

Skill Type: Foundation (Knowledge Base) Purpose: Define and validate requirement key patterns for traceability Prerequisites: None (foundation skill)

Agent Instructions

You provide the foundational knowledge for requirement traceability in AI SDLC.

Your role is to:

Define REQ-* key patterns
Validate requirement keys
Trace requirements through SDLC stages
Support other skills with traceability knowledge

Requirement Key Patterns

REQ-F-* (Functional Requirements)

Pattern: REQ-F-{DOMAIN}-{ID}

Examples:

<REQ-ID> - Authentication functionality
<REQ-ID> - Payment processing
REQ-F-PORTAL-001 - Customer portal features

Naming Rules:

DOMAIN: Uppercase, 2-10 chars (AUTH, PAY, PORTAL, USER, ADMIN)
ID: Zero-padded 3-digit number (001, 002, ..., 999)

Validation Regex: ^REQ-F-[A-Z]{2,10}-\d{3}$

REQ-NFR-* (Non-Functional Requirements)

Pattern: REQ-NFR-{TYPE}-{ID}

Types:

PERF - Performance (response time, throughput)
SEC - Security (authentication, authorization, encryption)
SCALE - Scalability (load handling, horizontal scaling)
AVAIL - Availability (uptime, SLA)
MAINT - Maintainability (code quality, documentation)
USABIL - Usability (UX, accessibility)

Examples:

REQ-NFR-PERF-001 - Response time < 500ms
REQ-NFR-SEC-001 - Password encryption required
REQ-NFR-SCALE-001 - Support 10,000 concurrent users

Validation Regex: ^REQ-NFR-(PERF|SEC|SCALE|AVAIL|MAINT|USABIL)-\d{3}$

REQ-DATA-* (Data Quality Requirements)

Pattern: REQ-DATA-{TYPE}-{ID}

Types:

CQ - Completeness (mandatory fields, null handling)
AQ - Accuracy (validation, range checks)
CONS - Consistency (cross-field validation)
TIME - Timeliness (freshness, latency)
LIN - Lineage (provenance, transformation tracking)
PII - Privacy/PII (encryption, masking, GDPR)

Examples:

REQ-DATA-CQ-001 - Email field mandatory
REQ-DATA-AQ-001 - Age between 0 and 150
REQ-DATA-PII-001 - Credit card numbers encrypted

Validation Regex: ^REQ-DATA-(CQ|AQ|CONS|TIME|LIN|PII)-\d{3}$

REQ-BR-* (Business Rules)

Pattern: REQ-BR-{DOMAIN}-{ID}

Use Cases:

Complex business logic requiring separate requirement
Multi-stage business processes
Regulatory compliance rules

Examples:

REQ-BR-REFUND-001 - Refund eligibility rules
REQ-BR-DISC-001 - Discount calculation rules
REQ-BR-COMP-001 - GDPR compliance rules

Validation Regex: ^REQ-BR-[A-Z]{2,10}-\d{3}$

Subordinate Key Patterns

These are nested within requirements for disambiguation:

BR-* (Business Rules - Nested)

Pattern: BR-{ID}

Examples (nested within <REQ-ID>):

BR-001: Email validation (regex pattern)
BR-002: Password minimum 12 characters
BR-003: Account lockout after 3 attempts

Use: Disambiguate vague requirements into specific rules

C-* (Constraints - Nested)

Pattern: C-{ID}

Examples (nested within <REQ-ID>):

C-001: PCI-DSS Level 1 compliance
C-002: Stripe API timeout 10 seconds
C-003: Transaction idempotency required

Use: Acknowledge ecosystem E(t) constraints

F-* (Formulas - Nested)

Pattern: F-{ID}

Examples (nested within <REQ-ID>):

F-001: Stripe fee = (amount * 0.029) + 0.30
F-002: Idempotency key = SHA256(merchant_id + timestamp + amount)

Use: Define precise calculations for code generation

Traceability Workflow

Forward Traceability (Intent → Runtime)

Path: Intent → Requirements → Design → Code → Tests → Runtime

INT-042: "Add user login"
  ↓ (Requirements stage)
<REQ-ID>: User login with email/password
  ↓ (Design stage)
AuthenticationService component
  ↓ (Code stage)
src/auth/login.py:23  # Implements: <REQ-ID>
  ↓ (Test stage)
tests/auth/test_login.py:15  # Validates: <REQ-ID>
  ↓ (Runtime stage)
Datadog metric: auth_success{req="<REQ-ID>"}

Operations:

# Find all artifacts for a requirement
git log --all --grep="<REQ-ID>"           # Commits
grep -rn "<REQ-ID>" src/                  # Implementation
grep -rn "<REQ-ID>" tests/                # Tests
grep -rn "<REQ-ID>" docs/requirements/    # Definition
grep -rn "<REQ-ID>" docs/design/          # Design

Backward Traceability (Runtime → Intent)

Path: Alert → Metric → Code → Requirement → Intent

Datadog alert: "ERROR: auth_timeout"
  ↓ (tagged with)
Metric: auth_latency{req="<REQ-ID>"}
  ↓ (find code)
src/auth/login.py:23  # Implements: <REQ-ID>
  ↓ (find requirement)
docs/requirements/auth.md:15  # <REQ-ID>
  ↓ (find original intent)
INT-042: "Add user login"

Operations:

# From alert, find requirement
grep "req=" alert.json | grep -o "REQ-[^\"]*"    # Extract REQ key from alert

# From requirement, find original intent
grep -rn "<REQ-ID>" docs/requirements/ | grep "INT-"

Validation Functions

Validate REQ-* Key Format

Rules:

Must start with REQ-
Followed by type: F, NFR, DATA, BR
Followed by domain/type (2-10 uppercase chars)
Followed by hyphen and 3-digit ID
Total max length: 30 characters

Valid Examples:

✅ <REQ-ID>
✅ REQ-NFR-PERF-001
✅ REQ-DATA-PII-001
✅ REQ-BR-REFUND-001

Invalid Examples:

❌ REQ-AUTH-001 (missing type: F/NFR/DATA/BR)
❌ REQ-F-auth-001 (domain must be uppercase)
❌ REQ-F-AUTH-1 (ID must be 3 digits)
❌ REQ-F-A-001 (domain too short, min 2 chars)

Extract REQ-* Keys from Text

Search patterns:

import re

def extract_req_keys(text: str) -> list[str]:
    """Extract all REQ-* keys from text"""
    pattern = r'REQ-(F|NFR|DATA|BR)-[A-Z]{2,10}-\d{3}'
    return re.findall(pattern, text)

# Example
text = "Implements: <REQ-ID>, REQ-NFR-SEC-001"
keys = extract_req_keys(text)  # ['<REQ-ID>', 'REQ-NFR-SEC-001']

Tagging Conventions

Code Implementation Tags

Format: # Implements: {REQ-KEY}

Examples:

# Implements: <REQ-ID>
def login(email: str, password: str) -> LoginResult:
    """User login functionality"""
    pass

# Implements: <REQ-ID>, BR-001
def validate_email(email: str) -> bool:
    """Email validation (BR-001)"""
    pass

Multiple implementations:

# Implements: <REQ-ID>, REQ-NFR-SEC-001
# This function satisfies both authentication and security requirements
def secure_login(email: str, password: str, mfa_token: str) -> LoginResult:
    pass

Test Validation Tags

Format: # Validates: {REQ-KEY}

Examples:

# Validates: <REQ-ID>
def test_user_login_with_valid_credentials():
    """Test successful login"""
    result = login("user@example.com", "SecurePass123!")
    assert result.success == True

# Validates: BR-001
def test_email_validation():
    """Test email format validation (BR-001)"""
    assert validate_email("invalid") == False

Commit Message Tags

Format: Include REQ-* in commit subject or footer

Examples:

feat: Add user login (<REQ-ID>)

Implements: <REQ-ID>
Validates: BR-001, BR-002, BR-003

Search commits:

# Find all commits for a requirement
git log --all --grep="<REQ-ID>"

# Find commits by requirement type
git log --all --grep="REQ-F-"      # All functional requirements
git log --all --grep="REQ-NFR-"    # All non-functional requirements

Runtime Telemetry Tags

Logs:

logger.info(
    "User login successful",
    extra={"req": "<REQ-ID>", "user_id": user.id}
)

Metrics (Datadog):

statsd.increment(
    "auth.login.success",
    tags=["req:<REQ-ID>", "env:production"]
)

Metrics (Prometheus):

auth_success_total{req="<REQ-ID>", env="production"}

Traceability Matrix

Structure

| REQ-* | Requirement Doc | Design | Code | Tests | Commits | Runtime | |-------|----------------|--------|------|-------|---------|---------| | <REQ-ID> | auth.md:15 | AuthService | login.py:23 | test_login.py:15 | 5 commits | Datadog ✅ | | REQ-NFR-PERF-001 | perf.md:8 | CacheLayer | cache.py:45 | test_cache.py:22 | 3 commits | Prometheus ✅ |

Query Operations

Find coverage gaps:

# Requirements with no code
grep -rh "^## REQ-" docs/requirements/ | \
  while read req; do
    grep -q "$req" src/ || echo "$req - NO CODE"
  done

# Requirements with no tests
grep -rh "^## REQ-" docs/requirements/ | \
  while read req; do
    grep -q "$req" tests/ || echo "$req - NO TESTS"
  done

Usage in Other Skills

In TDD Workflow

# tdd-workflow skill uses requirement-traceability to:
1. Validate REQ-* key format
2. Extract REQ-* from user intent
3. Tag code with "# Implements: REQ-*"
4. Tag tests with "# Validates: REQ-*"
5. Include REQ-* in commit messages

In Coverage Detection

# check-requirement-coverage skill uses requirement-traceability to:
1. Find all REQ-* keys in requirements docs
2. Search for "# Implements: REQ-*" in src/
3. Search for "# Validates: REQ-*" in tests/
4. Report requirements without coverage

In Code Generation

# autogenerate-from-business-rules skill uses requirement-traceability to:
1. Extract BR-*, C-*, F-* from REQ-*
2. Tag generated code with REQ-* and BR-*
3. Generate tests tagged with "# Validates: BR-*"

Configuration

Access via plugin configuration:

plugins:
  - name: "@aisdlc/aisdlc-core"
    config:
      req_key_patterns:
        functional: "REQ-F-{DOMAIN}-{ID}"
        non_functional: "REQ-NFR-{DOMAIN}-{ID}"
        data_quality: "REQ-DATA-{DOMAIN}-{ID}"
        business_rule: "REQ-BR-{DOMAIN}-{ID}"

      coverage:
        minimum_percentage: 80
        require_req_tags: true

      propagation:
        auto_propagate_on_commit: true
        tag_format: "# Implements: {REQ-KEY}"
        test_tag_format: "# Validates: {REQ-KEY}"

Traceability Operations

Operation 1: Trace Forward (REQ → Artifacts)

Input: <REQ-ID>

Output:

<REQ-ID>: User login with email/password
│
├─ 📋 Requirements
│   └─ docs/requirements/authentication.md:15
│
├─ 🎨 Design
│   ├─ docs/design/auth-service.md:42
│   └─ docs/adrs/ADR-003-auth-approach.md:10
│
├─ 💻 Implementation
│   ├─ src/auth/login.py:23  # Implements: <REQ-ID>
│   ├─ src/auth/validators.py:67  # Implements: <REQ-ID>, BR-001
│   └─ src/auth/lockout.py:34  # Implements: <REQ-ID>, BR-003
│
├─ ✅ Tests
│   ├─ tests/auth/test_login.py:15  # Validates: <REQ-ID>
│   ├─ tests/auth/test_validators.py:22  # Validates: BR-001
│   └─ features/authentication.feature:5  # Validates: <REQ-ID>
│
├─ 📦 Commits
│   ├─ abc123 "feat: Add user login (<REQ-ID>)"
│   ├─ def456 "fix: Correct email validation (<REQ-ID>, BR-001)"
│   └─ ghi789 "perf: Optimize login query (<REQ-ID>)"
│
└─ 🚀 Runtime
    ├─ Logs: logger.info("Login", extra={"req": "<REQ-ID>"})
    ├─ Metrics: auth_success{req="<REQ-ID>"}
    └─ Alerts: "ERROR: <REQ-ID> - Auth timeout"

Coverage: ✅ Full traceability

Implementation:

# Grep across all files
grep -rn "<REQ-ID>" docs/ src/ tests/ features/

# Git log
git log --all --grep="<REQ-ID>" --name-only

Operation 2: Trace Backward (Code → REQ)

Input: src/auth/login.py

Output:

src/auth/login.py implements:
├─ <REQ-ID> (line 23)
├─ REQ-NFR-SEC-001 (line 45)
└─ REQ-NFR-PERF-001 (line 89)

Tracing to requirements:
├─ <REQ-ID> → docs/requirements/authentication.md:15
│   └─ Intent: INT-042 "Add user login"
│
├─ REQ-NFR-SEC-001 → docs/requirements/security.md:8
│   └─ Intent: INT-043 "Secure authentication"
│
└─ REQ-NFR-PERF-001 → docs/requirements/performance.md:12
    └─ Intent: INT-050 "Optimize login performance"

Implementation:

# Extract REQ-* from file
grep "# Implements:" src/auth/login.py | grep -o "REQ-[^ ,]*"

# Find requirement definitions
for req in $(grep "# Implements:" src/auth/login.py | grep -o "REQ-[^ ,]*"); do
  grep -rn "^## $req" docs/requirements/
done

Operation 3: Coverage Report

Input: All requirements

Output:

Requirement Coverage Report
═══════════════════════════════════════════

Total Requirements: 42

By Type:
├─ REQ-F-*    : 28 (Functional)
├─ REQ-NFR-*  : 8  (Non-Functional)
├─ REQ-DATA-* : 4  (Data Quality)
└─ REQ-BR-*   : 2  (Business Rules)

Coverage by Stage:
├─ Requirements → Design: 100% (42/42) ✅
├─ Design → Code: 86% (36/42) ⚠️
├─ Code → Tests: 100% (36/36) ✅
├─ Tests → Runtime: 25% (9/36) ⚠️

Requirements Without Code (6):
├─ REQ-F-PROFILE-001 - User profile editing
├─ REQ-F-PROFILE-002 - Avatar upload
├─ REQ-F-NOTIF-001 - Email notifications
├─ REQ-F-NOTIF-002 - Push notifications
├─ REQ-NFR-PERF-002 - Database query optimization
└─ REQ-DATA-LIN-001 - Data lineage tracking

Requirements Without Runtime Telemetry (27):
├─ <REQ-ID> (has code, no metrics)
├─ REQ-F-AUTH-003 (has code, no metrics)
├─ ... (25 more)

Recommendations:
1. Implement 6 requirements missing code
2. Add telemetry tags to 27 requirements

Homeostasis Support

Sensor Skills Use This Skill To:

Validate REQ-* key format
Extract REQ-* from files
Check coverage gaps

Actuator Skills Use This Skill To:

Tag code with correct format
Create properly formatted commit messages
Generate traceability reports

Output Format

When invoked for validation:

[REQUIREMENT TRACEABILITY]

Validating: <REQ-ID>

Format Check:
  ✓ Starts with "REQ-"
  ✓ Type: F (Functional)
  ✓ Domain: AUTH (valid, 4 chars)
  ✓ ID: 001 (valid, 3 digits)

Result: ✅ VALID

Pattern: REQ-F-{DOMAIN}-{ID}
Regex: ^REQ-F-[A-Z]{2,10}-\d{3}$

When invoked for tracing:

[TRACE: <REQ-ID>]

Forward Traceability:
  ✅ Requirements: docs/requirements/auth.md:15
  ✅ Design: docs/design/auth-service.md:42
  ✅ Code: src/auth/login.py:23 (+ 2 more files)
  ✅ Tests: tests/auth/test_login.py:15 (+ 1 more files)
  ✅ Commits: 5 commits found
  ⚠️ Runtime: No telemetry tags (needs setup)

Coverage: 83% (5/6 stages)
Missing: Runtime telemetry

Notes

Why requirement traceability?

Compliance: Regulations require proof of implementation
Impact Analysis: Know what to change when requirement updates
Debugging: Trace production issues back to requirements
Audit Trail: Prove all requirements are implemented
Living Documentation: Code comments link to requirements

Key Principles:

REQ-* keys are immutable (content can evolve, keys never change)
REQ-* keys are unique (no duplicates)
REQ-* keys are human-readable (domain + sequential ID)
REQ-* keys are everywhere (requirements → code → tests → runtime)

Homeostasis Goal:

desired_state:
  all_requirements_have_unique_keys: true
  all_keys_follow_pattern: true
  all_artifacts_tagged: true
  full_traceability: true

"Excellence or nothing" 🔥