Skip to main content

​
Requirements Traceability Matrix

Generate a comprehensive traceability matrix that traces requirements through design to implementation and testing.

​
Command

arckit traceability <project ID or scope>

​
Arguments

  • scope (required): Project ID or “FR-xxx only” for filtered scope

​
Examples

arckit traceability "001"
arckit traceability "FR-xxx only"

​
Purpose

Create a comprehensive traceability matrix showing:
  1. Forward Traceability - Requirements → Design → Implementation → Tests
  2. Backward Traceability - Tests → Implementation → Design → Requirements
  3. Gap Analysis - Orphan requirements, orphan designs, orphan tests
  4. Coverage Metrics - Coverage by requirement type and priority

​
Traceability Chains

​
Forward Traceability

For each requirement:
  1. Requirement Details - ID, description, priority, category
  2. Design Mapping - Which HLD components implement this?
  3. Implementation Mapping - Source code files, APIs, database schemas
  4. Test Coverage - Unit tests, integration tests, UAT test cases
  5. Status - ✅ Fully implemented and tested / 🔄 In progress / ⏳ Planned / ❌ Not covered

​
Backward Traceability

For each test case:
  • Which requirements does it verify?
  • Which design components does it test?
  • What’s the expected outcome?

​
Gap Analysis

  • Orphan Requirements - Requirements with NO design references (GAP!)
  • Orphan Design Elements - IDs referenced in design but absent from REQ files (scope creep?)
  • Orphan Tests - Tests not linked to requirements
  • Coverage Gaps - Requirements without adequate test coverage

​
Coverage Metrics

The command provides:
  • Overall Coverage - Covered / Total / Percentage
  • Breakdown by Category - Business, Functional, Non-Functional, Integration, Data
  • Breakdown by Priority - MUST, SHOULD, MAY
  • Implementation Coverage - % with implementation evidence
  • Test Coverage - % with test references
Thresholds:
  • MUST requirements: Should be 100% covered
  • SHOULD requirements: Should be >80% covered
  • MAY requirements: Can be <50% covered

​
Risk Assessment

Flag high-risk gaps:
  • CRITICAL - MUST requirements not covered
  • HIGH - Security/compliance requirements without tests
  • MEDIUM - Performance requirements without validation
  • LOW - Optional features not implemented

​
Output

Generates ARC-{PROJECT_ID}-TRAC-v{VERSION}.md with:
  • Executive summary with traceability score (0-100)
  • Coverage by requirement type and priority
  • Critical gaps requiring attention
  • Detailed traceability matrix table
  • Gap analysis (orphan requirements, orphan design, untested requirements)
  • Coverage metrics with visual representation
  • Action items (blocking gaps, non-blocking gaps, technical debt)

​
Traceability Matrix Table

Req IDRequirementPriorityHLD ComponentDLD ModuleImplementationTestsStatus
BR-001Business reqMUST✅ HLD❌ Missing❌ Missing❌ Missing⚠️ Partial
FR-001FunctionalMUST✅ HLD, DLD✅ API✅ code.py✅ Tests✅ Complete
NFR-S-001SecurityMUST❌ Missing❌ Missing❌ Missing❌ Missing❌ Not Covered

​
Prerequisites

MANDATORY (warn if missing):
  • REQ (Requirements) - BR/FR/NFR/INT/DR requirements
RECOMMENDED (improves traceability):
  • Vendor HLD/DLD files - For design mapping
  • HLDR/DLDR (Design Reviews) - Design coverage evidence
  • BKLG (Product Backlog) - User stories and sprint mapping
  • DEVOPS (DevOps Strategy) - Test strategy

​
Hook Pre-processing

The Traceability Pre-processor Hook pre-extracts:
  1. All requirement IDs with categories, priorities, and descriptions
  2. All ADR, vendor HLD/DLD, and review file references to requirement IDs
  3. Coverage analysis: covered vs orphan requirements
  4. Coverage by category and priority
  5. Existing TRAC version for version numbering
The command uses this pre-extracted data directly (no need to re-read REQ files).

​
Version Detection

Before generating:
  1. Check for existing ARC-{PROJECT_ID}-TRAC-v*.md files
  2. If no existing file: Use VERSION=“1.0”
  3. If existing file found:
    • Minor increment (e.g., 1.0 → 1.1): Same scope — refreshed content
    • Major increment (e.g., 1.0 → 2.0): New requirement categories, significantly different coverage
  4. For v1.1+/v2.0+: Add Revision History entry

​
Use Cases

Compliance:
  • ISO, FDA, automotive standards require traceability
  • Audit trail for regulatory compliance
Impact Analysis:
  • Change requests: which tests/designs affected?
  • Scope changes: what’s the ripple effect?
Quality Assurance:
  • Go/no-go release decisions
  • Test coverage verification
  • Completeness checks
Accountability:
  • A requirement is only “done” when implemented AND tested
  • Missing traceability = missing accountability
  • arckit analyze - Comprehensive governance analysis (includes traceability)
  • arckit conformance - Architecture conformance (includes ADR traceability)
  • arckit health - Quick artifact health check

​
Important Notes

  • Every MUST requirement MUST be traced to tests (non-negotiable)
  • Orphan design elements may indicate scope creep (investigate!)
  • Orphan requirements may indicate incomplete design (blocking issue!)
  • Traceability matrix should be updated throughout project lifecycle

Build docs developers (and LLMs) love

Get started for freeTalk to us