Traceability Skill
Usage
code
/trace - Show traceability dashboard /trace generate - Scan artifacts and generate traceability matrix /trace coverage - Report traceability coverage metrics /trace orphans - Find artifacts without proper traces /trace REQ-xxx-nnn - Show full trace chain for a requirement /trace impact REQ-xxx-nnn - Show what would be affected if requirement changes /trace validate - Verify all trace links are valid /trace suggest - Auto-suggest traces for orphan artifacts
Commands
/trace (Dashboard)
Shows the current traceability health:
code
╔═══════════════════════════════════════════════════════════════════════╗ ║ TRACEABILITY DASHBOARD ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Matrix Last Updated: 2024-01-15 10:30:00 ║ ║ ║ ║ ARTIFACTS ║ ║ ├── Requirements: 25 ║ ║ ├── User Stories: 23 ║ ║ ├── Tasks: 18 ║ ║ ├── Specifications: 15 ║ ║ ├── Tests: 50 ║ ║ └── Implementations: 48 ║ ║ ║ ║ COVERAGE ║ ║ ├── Forward (Req → Code): 92% ✓ ║ ║ ├── Backward (Code → Req): 73% ⚠ ║ ║ └── Test Coverage: 84% ✓ ║ ║ ║ ║ ORPHANS: 8 artifacts need attention ║ ║ ║ ║ HEALTH SCORE: 82/100 ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ [G] Generate [C] Coverage [O] Orphans [V] Validate ║ ╚═══════════════════════════════════════════════════════════════════════╝
/trace generate
Scans all artifacts and generates the traceability matrix:
- •Scans PRD for REQ-IDs
- •Scans PRD/docs for User Stories (US-NNN)
- •Scans .taskmaster/tasks/tasks.json for tasks
- •Scans openspec/changes/*.md for specifications
- •Scans tests/**/*.{ts,js,py} for @traces annotations
- •Scans src/**/*.{ts,js,py} for @implements annotations
- •Generates
.claude/traceability/matrix.json
/trace coverage
Reports detailed coverage metrics with drill-down:
code
╔═══════════════════════════════════════════════════════════════════════╗ ║ TRACEABILITY COVERAGE REPORT ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ FORWARD TRACEABILITY ║ ║ ├── REQ → US: 23/25 (92%) ███████████░ ✓ ║ ║ ├── US → TASK: 18/23 (78%) ████████░░░░ ⚠ ║ ║ ├── TASK → SPEC: 15/18 (83%) █████████░░░ ✓ ║ ║ └── SPEC → CODE: 14/15 (93%) ███████████░ ✓ ║ ║ ║ ║ BACKWARD TRACEABILITY ║ ║ ├── TEST → REQ: 42/50 (84%) █████████░░░ ✓ ║ ║ └── CODE → REQ: 35/48 (73%) ████████░░░░ ⚠ ║ ║ ║ ║ GAPS: ║ ║ ├── REQ-PERF-003: No user stories ║ ║ ├── REQ-SEC-007: No implementation ║ ║ └── US-015, US-018, US-021, US-022, US-023: No tasks ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════╝
/trace orphans
Lists all artifacts without proper traces:
code
╔═══════════════════════════════════════════════════════════════════════╗ ║ ORPHAN ARTIFACTS ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ CRITICAL (Requirements with no path to implementation): ║ ║ ├── REQ-PERF-003: Response time < 100ms ║ ║ └── REQ-SEC-007: Audit logging ║ ║ ║ ║ WARNING (Code/tests without requirement link): ║ ║ ├── tests/unit/utils/helpers.test.ts ║ ║ ├── tests/unit/api/legacy.test.ts ║ ║ ├── src/utils/deprecated.ts ║ ║ └── src/api/v1/compat.ts ║ ║ ║ ║ MEDIUM (Tasks without requirement): ║ ║ └── TASK-042: Refactor database connection ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ [S] Suggest traces [M] Mark intentional [I] Ignore ║ ╚═══════════════════════════════════════════════════════════════════════╝
/trace REQ-xxx-nnn
Shows the complete trace chain for a single requirement:
code
╔═══════════════════════════════════════════════════════════════════════╗ ║ TRACE: REQ-AUTH-001 ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ REQ-AUTH-001: User authentication via email/password ║ ║ Priority: P0 | Source: docs/PRD.md:142 ║ ║ ║ ║ ┌─► US-001: User can log in ║ ║ │ ├─► TASK-003: Implement login API ║ ║ │ │ ├─► SPEC-003-01: Login endpoint spec ║ ║ │ │ │ └─► src/api/auth/login.ts ║ ║ │ │ └─► TEST-UNIT-015: tests/unit/auth/login.test.ts ║ ║ │ └─► TASK-004: Implement password validation ║ ║ │ ├─► SPEC-004-01: Password rules spec ║ ║ │ │ └─► src/services/auth.ts ║ ║ │ └─► TEST-UNIT-016: tests/unit/auth/password.test.ts ║ ║ │ ║ ║ └─► US-002: User receives error on invalid credentials ║ ║ └─► TASK-003: (shared) ║ ║ ║ ║ Coverage: FULL ✓ (all paths traced to code and tests) ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════╝
/trace impact REQ-xxx-nnn
Shows impact analysis for requirement changes:
code
╔═══════════════════════════════════════════════════════════════════════╗ ║ IMPACT ANALYSIS: REQ-AUTH-001 ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ If this requirement changes: ║ ║ ║ ║ ARTIFACTS AFFECTED: ║ ║ ├── 2 User Stories ║ ║ ├── 3 Tasks ║ ║ ├── 2 Specifications ║ ║ ├── 3 Code files ║ ║ └── 4 Test files ║ ║ ║ ║ ESTIMATED REWORK: ║ ║ ├── Complexity: HIGH ║ ║ ├── Files to modify: 9 ║ ║ └── Tests to update: 4 ║ ║ ║ ║ DOWNSTREAM DEPENDENCIES: ║ ║ └── REQ-SEC-002 (Session management) depends on this ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ [F] Show full artifact list [D] Show dependency graph ║ ╚═══════════════════════════════════════════════════════════════════════╝
/trace validate
Validates all trace links exist and are consistent:
code
╔═══════════════════════════════════════════════════════════════════════╗ ║ TRACE VALIDATION ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ BROKEN LINKS (referenced artifact doesn't exist): ║ ║ ├── TASK-007 references REQ-DATA-099 (not found) ║ ║ └── TEST-UNIT-042 references US-099 (not found) ║ ║ ║ ║ INCONSISTENT LINKS (bidirectional mismatch): ║ ║ └── US-015 links to TASK-012, but TASK-012 doesn't link back ║ ║ ║ ║ DUPLICATE IDS: ║ ║ └── None found ✓ ║ ║ ║ ║ VALIDATION: 3 issues found ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════╝
/trace suggest
Auto-suggests traces for orphan artifacts:
code
╔═══════════════════════════════════════════════════════════════════════╗ ║ TRACE SUGGESTIONS ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ ║ ║ tests/unit/auth/session.test.ts ║ ║ Currently orphan (no @traces annotation) ║ ║ ║ ║ Suggested traces (by content similarity): ║ ║ ├── REQ-AUTH-002 (85%) - Session management ║ ║ ├── US-004 (78%) - User session handling ║ ║ └── TASK-008 (72%) - Implement session storage ║ ║ ║ ║ Recommended annotation: ║ ║ /** ║ ║ * @traces REQ-AUTH-002, US-004, TASK-008 ║ ║ */ ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════╣ ║ [A] Apply suggestion [S] Skip [M] Manual entry ║ ╚═══════════════════════════════════════════════════════════════════════╝
Integration
With Audit Orchestrator
The traceability-auditor is invoked as part of audit dimension F01 (Requirements Coverage).
With Phase Gates
- •Phase 5: Verify all requirements have tasks
- •Phase 6: Verify all tasks have specifications
- •Phase 8: Verify all tests have traces
- •Phase 10: Verify full forward/backward traceability
With Plan Guardian
When Plan Guardian detects drift, it can use traceability to identify which requirements are affected.
Files
| File | Purpose |
|---|---|
.claude/traceability/matrix.json | Generated traceability matrix |
templates/requirement-traceability.schema.yaml | Schema reference |