Requirements Traceability

Generate comprehensive traceability matrices from requirements to design to tests

ArcKit’s /arckit.traceability command generates comprehensive traceability matrices that trace requirements through design to implementation and testing, ensuring complete coverage and identifying gaps.

What This Command Does

The /arckit.traceability command automatically:

1. Forward Traceability: Requirements → Design → Implementation → Tests
2. Backward Traceability: Tests → Implementation → Design → Requirements
3. Gap Analysis: Identifies orphan requirements, orphan design elements, and untested requirements
4. Coverage Metrics: Calculates coverage by requirement type and priority
5. Risk Assessment: Flags high-risk gaps (MUST requirements without coverage)
6. Audit Trail: Creates compliance-ready documentation for ISO, FDA, automotive, etc.

When to Run This Command

Timing: Multiple times throughout the project lifecycle

• After HLD Review: Verify all requirements mapped to high-level components
• After DLD Review: Verify all requirements mapped to detailed modules
• Before Each Sprint: Ensure sprint backlog traces to requirements
• Before Release: Go/no-go decision based on traceability score
• During Audits: Provide compliance evidence

Prerequisites:

• MANDATORY: Requirements document (ARC-*-REQ-*.md)
• RECOMMENDED:
  • HLD files (vendors/*/hld-v*.md)
  • DLD files (vendors/*/dld-v*.md)
  • ADRs (vendors/*/decisions/adr-*.md)
  • Test plans or test case references

Basic Usage

# Generate traceability matrix for a project
/arckit.traceability Generate traceability matrix for payment gateway project

# Update existing traceability (version increment)
/arckit.traceability Update traceability for project 001

How It Works

Step 1: Requirements Extraction

The command uses a pre-processor hook that automatically:

1. Extracts all requirement IDs (BR, FR, NFR, INT, DR) from ARC-*-REQ-*.md
2. Captures categories, priorities, descriptions for each requirement
3. Scans all ADRs, HLD/DLD files for requirement ID references
4. Computes coverage: covered vs orphan requirements
5. Detects existing TRAC version for version numbering

The hook runs before the command executes, so traceability data is pre-extracted and ready to use. You don’t need to manually scan files.

Step 2: Forward Traceability

For each requirement, the matrix shows:

Requirement	Description	Priority	HLD Component	DLD Module	Implementation	Tests	Status
FR-001	User Registration	Must Have	User Service	UserController.register()	/api/users/register	TC-001, TC-002	✅ Fully covered
NFR-S-001	PCI-DSS compliance	Must Have	Security Architecture	TokenVault, Encryption	security/vault.ts	SEC-001 to SEC-015	✅ Fully covered
BR-003	Cost savings	Should Have	—	—	—	—	❌ Not covered (GAP!)

Status Indicators:

• ✅ Fully implemented and tested
• 🔄 In progress (design exists, implementation partial)
• ⏳ Planned (design exists, no implementation yet)
• ❌ Not covered (GAP - no design reference)

Step 3: Backward Traceability

For each test case:

Test ID	Test Description	Requirements Verified	Component Tested	Expected Outcome
TC-001	User registration happy path	FR-001	User Service	201 Created with user ID
TC-002	User registration invalid email	FR-001	User Service	400 Bad Request
SEC-015	PCI-DSS token storage	NFR-S-001	Token Vault	Tokens encrypted at rest

Step 4: Gap Analysis

The command identifies:

Orphan Requirements

Requirements with NO design references:

### Orphan Requirements (Not in Design)

**CRITICAL GAPS** (Must Have):
- BR-003: Cost savings - No success metrics defined
- FR-042: Payment reconciliation - Missing from HLD/DLD

**Non-Blocking Gaps** (Should/Could Have):
- NFR-P-005: Database indexing - Not specified in DLD

Orphan Design Elements

IDs referenced in design docs but absent from REQ files (scope creep?):

### Design-Only References (Scope Creep?)

- FR-099: Real-time notifications - Found in HLD but not in requirements
- INT-055: Slack integration - Found in DLD but not in requirements

Orphan Tests

Tests not linked to requirements (what are they testing?):

### Orphan Tests (No Requirement Link)

- TEST-042: Load testing (1000 concurrent users) - No NFR link
- TEST-053: Edge case: negative currency values - No FR link

Coverage Gaps

Requirements without adequate test coverage:

### Requirements Without Tests

**CRITICAL** (Must Have):
- NFR-R-002: 99.99% uptime - No disaster recovery tests
- NFR-S-012: Role-based access control - No authorization tests

**HIGH** (Should Have):
- NFR-P-003: Database performance - Missing load tests

Coverage Metrics

The command provides detailed coverage analysis:

Overall Coverage

## Coverage Summary

| Category | Total | Covered | Orphan | Coverage % |
|----------|-------|---------|--------|------------|
| **Overall** | 85 | 73 | 12 | 85.9% |
| Business Requirements | 8 | 7 | 1 | 87.5% |
| Functional Requirements | 42 | 40 | 2 | 95.2% |
| Non-Functional Requirements | 28 | 23 | 5 | 82.1% |
| Integration Requirements | 5 | 5 | 0 | 100.0% |
| Data Requirements | 2 | 2 | 0 | 100.0% |

Priority Coverage

| Priority | Total | Covered | Orphan | Coverage % |
|----------|-------|---------|--------|------------|
| MUST | 45 | 44 | 1 | 97.8% |
| SHOULD | 28 | 22 | 6 | 78.6% |
| MAY | 12 | 7 | 5 | 58.3% |

Thresholds:

• ✅ MUST requirements: Should be 100% covered (blocking if < 100%)
• ⚠️ SHOULD requirements: Should be > 80% covered
• ℹ️ MAY requirements: Can be < 50% covered

Risk Assessment

The command flags high-risk gaps:

Risk Levels

Risk	Description	Example
🔴 CRITICAL	MUST requirements not covered	BR-003: Cost savings has no success metrics
🟠 HIGH	Security/compliance requirements without tests	NFR-S-001: PCI-DSS compliance not validated
🟡 MEDIUM	Performance requirements without validation	NFR-P-002: Response time not load tested
🟢 LOW	Optional features not implemented	NFR-U-008: Dark mode theme (Could Have)

Example Risk Matrix

## Risk Assessment

### Critical Gaps (BLOCKING)

1. **BR-003: Cost savings** (Must Have)
   - **Gap**: No design reference, no success metrics defined
   - **Impact**: Cannot measure project ROI
   - **Recommendation**: Define cost tracking mechanism in HLD
   - **Owner**: Product Owner, Enterprise Architect
   - **Deadline**: Before Beta phase gate

2. **NFR-R-002: 99.99% uptime** (Must Have)
   - **Gap**: No disaster recovery tests planned
   - **Impact**: Cannot prove availability SLA
   - **Recommendation**: Create DR runbook and chaos engineering tests
   - **Owner**: Platform Engineer, SRE Team
   - **Deadline**: Before Live phase gate

Traceability Score

The command calculates an overall traceability score (0-100):

## Traceability Score: 85/100

**Rating**: Good (Gaps must be addressed)

**Score Breakdown**:
- Requirements coverage: 85.9% (73/85) → 43/50 points
- Priority coverage (MUST): 97.8% (44/45) → 24/25 points
- Test coverage: 78% (66/85) → 19/25 points

**Recommendation**: APPROVED WITH CONDITIONS
- Address 1 critical gap (BR-003)
- Address 2 high-risk gaps (NFR-R-002, NFR-S-012)
- Non-blocking gaps can be deferred to future sprints

Score Interpretation:

• 90-100: Excellent - Ready for release
• 75-89: Good - Gaps must be addressed before release
• 60-74: Fair - Significant rework needed
• < 60: Poor - Not ready for release

Output File

File: ARC-{PROJECT_ID}-TRAC-v1.0.md

Contents:

• Executive summary with traceability score
• Coverage metrics (overall, by category, by priority)
• Detailed traceability matrix (all requirements)
• Gap analysis (orphan requirements, orphan design, orphan tests)
• Risk assessment with action items
• Appendices (dependency graph, glossary)

Version Numbering

The hook automatically detects existing TRAC versions:

• First run: v1.0
• Subsequent runs:
  • Minor increment (v1.0 → v1.1) if scope unchanged
  • Major increment (v1.0 → v2.0) if scope materially changed

Major increment triggers:

• New requirement categories traced
• Fundamentally different coverage approach
• Significant new artifacts added

Best Practices

1. Run Traceability Regularly

Weekly during active development:

/arckit.traceability Update traceability for project 001

Track coverage trend over time.

2. Use for Go/No-Go Decisions

Before phase gates (Alpha → Beta → Live):

• Alpha gate: 70%+ coverage acceptable (proof of concept)
• Beta gate: 85%+ coverage required (production-ready)
• Live gate: 95%+ coverage required (all MUST requirements covered)

3. Link to Sprint Planning

Use traceability to identify sprint priorities:

# Generate backlog (includes traceability)
/arckit.backlog

# Verify coverage
/arckit.traceability

Sprints should prioritize stories that close coverage gaps.

4. Include in Design Reviews

Before HLD/DLD approval:

# Review design
/arckit.hld-review

# Check traceability
/arckit.traceability

Design reviews should verify all requirements are addressed.

5. Use for Audit Compliance

For ISO 9001, ISO 13485, IEC 62304, FDA, automotive (ISO 26262):

• Traceability matrix proves requirements → design → implementation → tests
• Orphan requirements prove nothing was missed
• Coverage metrics prove adequate testing

Real-World Examples

Example 1: NHS Appointment Booking

Command:

/arckit.traceability Generate traceability matrix for NHS appointment booking

Result:

• 87 requirements traced
• 85.9% coverage (73 covered, 14 orphan)
• 1 critical gap: BR-006 (Cost savings) has no success metrics
• 2 high-risk gaps: NFR-R-002 (99.99% uptime), NFR-S-008 (NHS Spine auth)
• Traceability score: 82/100 (Good)
• Recommendation: Address 3 gaps before Beta gate

Example 2: Payment Gateway

Command:

/arckit.traceability Update traceability for payment gateway project

Result:

• 52 requirements traced
• 96.2% coverage (50 covered, 2 orphan)
• 0 critical gaps
• 1 high-risk gap: NFR-S-001 (PCI-DSS) missing penetration test evidence
• Traceability score: 94/100 (Excellent)
• Recommendation: Address 1 gap, then ready for Live

Compliance Use Cases

ISO 9001 (Quality Management)

Required: Documented traceability from customer requirements to verification

ArcKit provides:

• Requirements → Design → Implementation → Tests traceability
• Gap analysis proves completeness
• Audit trail for change management

ISO 13485 (Medical Devices)

Required: Design and development outputs traceable to inputs

ArcKit provides:

• Forward traceability: Requirements → Design outputs
• Backward traceability: Tests → Requirements
• Risk analysis for safety requirements

IEC 62304 (Medical Device Software)

Required: Software requirements → architecture → detailed design → tests

ArcKit provides:

• Multi-level traceability (BR → FR → NFR → HLD → DLD → Tests)
• Verification evidence for each requirement
• Hazard analysis linkage (via risk register)

FDA 21 CFR Part 11 (Electronic Records)

Required: Traceability of changes and audit trail

ArcKit provides:

• Version-controlled traceability documents
• Document control metadata (reviewer, approver, dates)
• Revision history

Automotive ISO 26262 (Functional Safety)

Required: Safety requirements → safety goals → implementation → validation

ArcKit provides:

• ASIL-rated requirements traceability
• Safety requirements mapped to design elements
• Verification matrix (requirement → test case)

Troubleshooting

Low Coverage Score

Symptom: Coverage < 80%, many orphan requirements

Causes:

1. Requirements not referenced in HLD/DLD
2. HLD/DLD use different requirement IDs
3. Requirements changed after design

Fix:

1. Update HLD/DLD to reference requirements explicitly
2. Ensure requirement IDs match exactly (case-sensitive)
3. Re-run traceability after design updates

Orphan Design Elements

Symptom: Design references IDs not in requirements

Causes:

1. Scope creep (new features added without requirements)
2. Typos in HLD/DLD (FR-042 vs FR-043)
3. Requirements deleted but design not updated

Fix:

1. Add missing requirements to ARC-*-REQ-*.md
2. Fix typos in HLD/DLD
3. Remove obsolete design sections

Orphan Tests

Symptom: Tests not linked to requirements

Causes:

1. Test cases don’t reference requirement IDs
2. Exploratory tests without formal requirements

Fix:

1. Add requirement IDs to test case descriptions
2. Create requirements for exploratory findings

Further Reading

• Sprint Planning Guide - Link traceability to user stories
• Customizing Templates - Customize traceability template
• Upgrading Guide - Preserve traceability during upgrades