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:
- Forward Traceability: Requirements → Design → Implementation → Tests
- Backward Traceability: Tests → Implementation → Design → Requirements
- Gap Analysis: Identifies orphan requirements, orphan design elements, and untested requirements
- Coverage Metrics: Calculates coverage by requirement type and priority
- Risk Assessment: Flags high-risk gaps (MUST requirements without coverage)
- 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
The command uses a pre-processor hook that automatically:
- Extracts all requirement IDs (BR, FR, NFR, INT, DR) from
ARC-*-REQ-*.md
- Captures categories, priorities, descriptions for each requirement
- Scans all ADRs, HLD/DLD files for requirement ID references
- Computes coverage: covered vs orphan requirements
- 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!) |
- ✅ 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% |
- ✅ 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
- 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
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
4. Include in Design Reviews
Before HLD/DLD approval:
# Review design
/arckit.hld-review
# Check traceability
/arckit.traceability
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
- 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
- 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:
- Requirements not referenced in HLD/DLD
- HLD/DLD use different requirement IDs
- Requirements changed after design
Fix:
- Update HLD/DLD to reference requirements explicitly
- Ensure requirement IDs match exactly (case-sensitive)
- Re-run traceability after design updates
Orphan Design Elements
Symptom: Design references IDs not in requirements
Causes:
- Scope creep (new features added without requirements)
- Typos in HLD/DLD (FR-042 vs FR-043)
- Requirements deleted but design not updated
Fix:
- Add missing requirements to
ARC-*-REQ-*.md
- Fix typos in HLD/DLD
- Remove obsolete design sections
Orphan Tests
Symptom: Tests not linked to requirements
Causes:
- Test cases don’t reference requirement IDs
- Exploratory tests without formal requirements
Fix:
- Add requirement IDs to test case descriptions
- Create requirements for exploratory findings
Further Reading