Agent skill

create-traceability-matrix

Create traceability matrix mapping intents (INT-*) to requirements (REQ-*) and requirements to all downstream artifacts (design, code, tests, commits, runtime). Use to visualize and verify complete traceability.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/create-traceability-matrix-foolishimp-ai-sdlc-method

SKILL.md

create-traceability-matrix

Skill Type: Sensor/Reporter (Traceability Management) Purpose: Create and maintain traceability matrix for impact analysis Prerequisites: Requirements and intents exist

Agent Instructions

You are creating a traceability matrix showing the complete lineage from intent → runtime.

Matrix maps:

  • Intent (INT-) → Requirements (REQ-)
  • Requirements (REQ-*) → Design, Code, Tests, Commits, Runtime

Purpose: Impact analysis, coverage verification, compliance auditing

Matrix Structure

Full Traceability Matrix

INT-* REQ-* Design Code Tests Commits Runtime Status
INT-042 <REQ-ID> AuthService login.py:23 test_login.py:15 5 Datadog ✅ ✅ Complete
INT-042 REQ-F-PORTAL-001 PortalService balance.py:12 test_balance.py:8 3 Datadog ✅ ✅ Complete
INT-042 REQ-F-PORTAL-002 ProfileService profile.py:45 test_profile.py:22 2 ❌ No metrics ⚠️ Partial
INT-050 REQ-NFR-PERF-001 CacheLayer cache.py:67 test_cache.py:34 4 Prometheus ✅ ✅ Complete

Workflow

Step 1: Collect Intent → Requirements Mapping

bash
# Find all intents and their requirements
grep -rh "^# Intent:" docs/requirements/ | sort -u
grep -rh "^## REQ-" docs/requirements/ | sort -u

Output format:

yaml
# docs/traceability/intent-to-requirements.yml

INT-042:
  title: "Customer self-service portal"
  date: "2025-11-20"
  status: "In Progress"
  requirements:
    - <REQ-ID>
    - <REQ-ID>
    - REQ-F-PORTAL-001
    - REQ-F-PORTAL-002
    - REQ-F-PORTAL-003
  count: 5

Step 2: Collect Requirements → Design Mapping

bash
# Find design documents mentioning requirements
grep -rn "REQ-" docs/design/ docs/adrs/

Step 3: Collect Requirements → Code Mapping

bash
# Find code implementing requirements
grep -rn "# Implements: REQ-" src/

Step 4: Collect Requirements → Tests Mapping

bash
# Find tests validating requirements
grep -rn "# Validates: REQ-" tests/ features/

Step 5: Collect Requirements → Commits Mapping

bash
# Find commits for each requirement
for req in $(grep -rho "REQ-[A-Z-]*-[0-9]*" docs/requirements/ | sort -u); do
  echo "$req:"
  git log --all --oneline --grep="$req"
done

Step 6: Generate Matrix Document

Create comprehensive matrix:

markdown
# Traceability Matrix

**Generated**: 2025-11-20 23:30:00
**Total Intents**: 12
**Total Requirements**: 42
**Coverage**: 86%

---

## Intent: INT-042 (Customer Self-Service Portal)

**Status**: 60% Complete (3/5 requirements implemented)

| REQ-* | Description | Design | Code | Tests | Commits | Runtime | Status |
|-------|-------------|--------|------|-------|---------|---------|--------|
| <REQ-ID> | User login | AuthService | ✅ login.py | ✅ test_login.py | ✅ 5 | ✅ Datadog | ✅ |
| <REQ-ID> | Password reset | EmailService | ✅ reset.py | ✅ test_reset.py | ✅ 3 | ⚠️ Partial | ⚠️ |
| REQ-F-PORTAL-001 | View balance | PortalService | ✅ balance.py | ✅ test_balance.py | ✅ 2 | ❌ None | ⚠️ |
| REQ-F-PORTAL-002 | Update profile | ProfileService | ❌ None | ❌ None | ❌ 0 | ❌ None | ❌ |
| REQ-F-PORTAL-003 | Download invoices | ❌ No design | ❌ None | ❌ None | ❌ 0 | ❌ None | ❌ |

**Summary**:
- Design: 80% (4/5)
- Code: 60% (3/5)
- Tests: 60% (3/5)
- Runtime: 40% (2/5)

---

## Intent: INT-050 (Performance Optimization)

**Status**: 100% Complete (2/2 requirements implemented)

| REQ-* | Description | Design | Code | Tests | Commits | Runtime | Status |
|-------|-------------|--------|------|-------|---------|---------|--------|
| REQ-NFR-PERF-001 | Login <500ms | CacheLayer | ✅ cache.py | ✅ test_cache.py | ✅ 4 | ✅ Prometheus | ✅ |
| REQ-NFR-PERF-002 | DB queries <100ms | QueryOptimizer | ✅ optimizer.py | ✅ test_optimizer.py | ✅ 3 | ✅ Datadog | ✅ |

**Summary**: All complete ✅

Output Format

[TRACEABILITY MATRIX]

Generated: 2025-11-20 23:30:00

Total Intents: 12
Total Requirements: 42

Overall Coverage:
  Design: 95% (40/42) ✅
  Code: 86% (36/42) ⚠️
  Tests: 83% (35/42) ⚠️
  Commits: 86% (36/42) ⚠️
  Runtime: 24% (10/42) ❌

Coverage Gaps:

Requirements Without Code (6):
  - REQ-F-PROFILE-002
  - REQ-F-PORTAL-003
  - REQ-F-NOTIF-001
  - REQ-F-NOTIF-002
  - REQ-NFR-SCALE-001
  - REQ-DATA-LIN-001

Requirements Without Tests (7):
  - <REQ-ID> (has code, no tests)
  - REQ-F-CART-001 (has code, no tests)
  ... (5 more)

Requirements Without Runtime Telemetry (32):
  - Most requirements (needs telemetry setup)

Matrix Files Created:
  + docs/traceability/intent-to-requirements.yml
  + docs/traceability/requirements-matrix.md
  + docs/traceability/coverage-report.md

✅ Traceability Matrix Created!

Notes

Why traceability matrix?

  • Impact analysis: Know what breaks if requirement changes
  • Coverage verification: Ensure all requirements implemented and tested
  • Compliance auditing: Prove requirements → code → tests → runtime
  • Gap detection: Find requirements without coverage

Homeostasis Goal:

yaml
desired_state:
  traceability_complete: true
  all_stages_covered: true
  coverage_percentage: >= 80%

"Excellence or nothing" 🔥

Didn't find tool you were looking for?

Be as detailed as possible for better results