Traceability check

​

When to use

• Verify the full chain: REQ → UC → WF → API → BDD → INV → ADR → TASK → COMMIT → CODE → TEST
• Find artifacts that are defined but never referenced (orphans)
• Find references to artifacts that don’t exist (broken links)
• Verify that completed tasks have git commits with proper trailers
• Check that code and test references are still valid (when code intelligence available)

​

Invocation

/sdd:traceability-check

​

How it works

​

Step 1: Collect all defined IDs

​

Step 2: Collect all referenced IDs

​

Step 3: Cross-reference analysis

1. Orphaned definitions: IDs that are defined but never referenced by any other artifact
2. Broken references: IDs that are referenced but never defined
3. Forward references: IDs referenced in upstream artifacts pointing to downstream artifacts (acceptable but noted)

​

Step 4: Traceability matrix

| REQ | UC | WF | API | BDD | INV | ADR |
|-----|----|----|-----|-----|-----|-----|
| REQ-001 | UC-001, UC-002 | WF-001 | API-001 | BDD-001 | INV-001 | ADR-001 |
| REQ-002 | UC-003 | — | API-002 | — | — | — |

​

Step 5: Commit chain verification

1. Check git availability: Gracefully skips if not inside a git repository
2. Extract commits with Refs: and Task: trailers from git log (limit 500 for performance)
3. Build TASK → commits mapping: A task may have multiple commits
4. Identify gaps:
   • Tasks without commits: TASKs marked [x] but no matching commit in git log
   • Commits without refs: Commits with Task: trailer but no Refs: trailer (missing upstream traceability)
   • Commits with broken refs: Commits whose Refs: trailer references artifact IDs not defined in any spec
5. Compute commit coverage: Tasks with at least one commit / total completed tasks

​

Step 5.5: Code & test chain verification (optional)

1. Verify codeRef validity:
   • Check that referenced files exist on disk
   • Check that symbols still exist at registered locations
   • Mark as valid, stale (file exists but symbol moved), or broken (file missing)
2. Verify testRef validity:
   • Check that test files exist on disk
   • Check that named test blocks exist
   • Mark as valid, stale, or broken
3. Detect orphaned code annotations:
   • Scan src/ for Refs: comments that reference artifact IDs not defined in any SDD artifact
   • These indicate stale annotations left after spec changes
4. Detect uncovered paths:
   • Using the call graph from codeIntelligence.callGraph[]
   • Find exported/public symbols reachable from entry points (route handlers, main exports)
   • Identify those with NO Refs: annotation and no inferred refs
   • These are execution paths with no SDD traceability
5. Compute code-test chain coverage:
   • codeRefs: valid / stale / broken counts
   • testRefs: valid / stale / broken counts
   • Orphaned annotations: count
   • Uncovered paths: count
   • Code chain coverage: valid codeRefs / total codeRefs

​

Step 6: Generate report

## SDD Traceability Report

### Summary
- Total defined IDs: 245
- Total references: 412
- Orphaned definitions: 3
- Broken references: 1
- Coverage: 87% of REQs fully traceable
- Commit coverage: 92% of completed tasks have commits

### Orphaned Definitions (defined but never referenced)
| ID | Defined In | Type |
|----|-----------|------|
| INV-005 | spec/domain-model.md:42 | Invariant |

### Broken References (referenced but never defined)
| ID | Referenced In | Type |
|----|--------------|------|
| UC-099 | spec/workflows.md:15 | Use Case |

### Commit Traceability
- Tasks with commits: 87/95 (92%)
- Commits with valid refs: 94/128
- Commits with task trailers: 87/128

#### Tasks Without Commits
| Task | FASE | Status | Expected Commit |
|------|------|--------|----------------|
| TASK-F0-005 | FASE-0 | [x] Complete | feat(auth): add rate limiting |

#### Commits Without Refs
| SHA | Message | Task | Issue |
|-----|---------|------|-------|
| abc1234 | chore(bootstrap): init project | TASK-F0-001 | No Refs: trailer |

#### Orphaned Commit References
| SHA | Message | Broken Ref |
|-----|---------|------------|
| def5678 | feat(auth): add middleware | UC-099 (not defined) |

### Traceability Matrix
[condensed matrix]

### Recommendations
- Define UC-099 or remove references
- Add cross-references for orphaned INV-005
- Add Refs: trailer to commits missing upstream traceability

​

Constraints

• Read-only: Never modifies any files
• Precise line numbers: Reports include exact file locations
• Graceful degradation: If a directory doesn’t exist, skips it and notes “not yet generated”
• Tolerates partial pipelines: Not all stages need to be complete
• Git optional: Commit verification gracefully skips if git not available
• Code intelligence optional: Step 5.5 runs only when code index exists

​

Example use cases

​

After requirements change

/sdd:req-change         # Make requirements changes
/sdd:traceability-check # Verify no broken links introduced

​

Before auditing

/sdd:traceability-check # Find structural issues first
/sdd:spec-auditor       # Then audit content quality

​

After implementation

/sdd:task-implementer   # Implement tasks with commits
/sdd:traceability-check # Verify commit chain integrity

​

Related skills