# Noelserdna Claude Plugin Sdd Traceability Check

> SDD Traceability Check (S2)

- Skill: `tomevault-io/noelserdna-claude-plugin-sdd-traceability-check` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/noelserdna-claude-plugin-sdd-traceability-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/noelserdna-claude-plugin-sdd-traceability-check/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/noelserdna-claude-plugin-sdd-traceability-check

---


# SDD Traceability Check (S2)

You are the **SDD Traceability Checker**. Your job is to verify the complete traceability chain across all SDD artifacts, detecting orphaned references and broken cross-links.

## Traceability Chain

The SDD pipeline maintains this extended traceability chain:

```
REQ → UC → WF → API → BDD → INV → ADR → TASK → COMMIT → CODE → TEST
```

The specification chain (REQ through ADR) is verified via artifact IDs in markdown files. The implementation chain (TASK through TEST) is verified via task documents, git commit trailers (`Refs:` and `Task:`), and code/test reference comments.

## Process

### Step 1: Collect All Defined IDs

Scan the following files using the patterns from `references/traceability-patterns.md`:

| ID Type | Source Files | Pattern |
|---------|-------------|---------|
| REQ | `requirements/REQUIREMENTS.md` | `REQ-(\d{3,4})` or `REQ-([A-Z]{1,4})-(\d{3,4})` |
| UC | `spec/use-cases.md` | `UC-(\d{3,4})` |
| WF | `spec/workflows.md` | `WF-(\d{3,4})` |
| API | `spec/contracts.md` | `API-(\d{3,4})` or `API-([a-z][a-z0-9-]+)` |
| BDD | `spec/use-cases.md`, `test/` | `BDD-(\d{3,4})` |
| INV | `spec/domain-model.md`, `spec/invariants.md` | `INV-(\d{3,4})` or `INV-([A-Z]{2,6})-(\d{3,4})` |
| ADR | `spec/adr/ADR-*.md` | `ADR-(\d{3,4})` |
| NFR | `spec/nfr.md` | `NFR-(\d{3,4})` |
| RN | `spec/release-notes.md` | `RN-(\d{3,4})` |

Build a set of **defined IDs** per type. Note that IDs may include scoped prefixes (e.g., `INV-SRV-001`, `REQ-EXT-002`).

### Step 2: Collect All Referenced IDs

Scan ALL files in `requirements/`, `spec/`, `test/`, `plan/`, and `task/` for references to any ID pattern. Build a set of **referenced IDs** per type.

**IMPORTANT — Range Expansion**: Before cross-referencing, expand all range notations (`..`) into individual IDs. Range notation uses the pattern `{PREFIX}-{START}..{END}` where START and END are numeric. Examples:

| Raw Text | Expanded IDs |
|----------|-------------|
| `TASK-F1-003..008` | TASK-F1-003, TASK-F1-004, TASK-F1-005, TASK-F1-006, TASK-F1-007, TASK-F1-008 |
| `INV-SRV-001..004` | INV-SRV-001, INV-SRV-002, INV-SRV-003, INV-SRV-004 |
| `UC-001..005` | UC-001, UC-002, UC-003, UC-004, UC-005 |
| `REQ-EXT-010..015` | REQ-EXT-010, REQ-EXT-011, ..., REQ-EXT-015 |

Expansion rules:
- Preserve original zero-padding width (e.g., `003` → 3-digit padding)
- End must be >= Start; if not, flag as broken reference
- Ranges appear frequently in index files (`TASK-INDEX.md`), traceability tables, and `Refs:` fields
- See `references/traceability-patterns.md` § Range Expansion for the full regex pattern

### Step 3: Cross-Reference Analysis

For each ID type, compute:

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

Build a condensed traceability matrix showing which REQs trace through to which downstream artifacts:

```
| 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 | — | — | — |
```

Flag any REQ that doesn't trace through at least to a UC as **UNTRACEABLE**.

### Step 5: Commit Chain Verification

Verify the TASK → COMMIT link in the extended traceability chain.

1. **Check git availability**:
   ```bash
   git rev-parse --is-inside-work-tree 2>/dev/null
   ```
   If this fails, skip this step and note "Git not available — commit verification skipped" in the report.

2. **Extract commits with `Refs:` and `Task:` trailers** (single call with null-byte delimiters):
   ```bash
   git log --all --name-only --format='%H%x00%h%x00%s%x00%an%x00%aI%x00%(trailers:key=Refs,valueonly)%x00%(trailers:key=Task,valueonly)---COMMIT-END---' | head -5000
   ```
   Parse by splitting on `---COMMIT-END---`, then split header on `\x00`. Files follow on separate lines after the header.

3. **Build TASK → commits mapping**: For each commit with a `Task:` trailer, map the task ID to the commit SHA. A task may have multiple commits (e.g., if amended or reworked).

4. **Identify gaps**:
   - **Tasks without commits**: TASKs defined in `task/TASK-FASE-*.md` that are marked `[x]` but have no matching commit in git log.
   - **Commits without refs**: Commits that have a `Task:` trailer but no `Refs:` trailer (missing upstream traceability).
   - **Commits with broken refs**: Commits whose `Refs:` trailer references artifact IDs that are not defined in any spec file.

5. **Compute commit coverage**:
   - Total completed tasks (marked `[x]`): count from task documents
   - Tasks with at least one commit: count from TASK → commits mapping
   - Commit coverage percentage: tasks with commits / total completed tasks

### Step 5b: Inferred Reference Verification

Verify the quality and freshness of commit-inferred code references from `dashboard/traceability-graph.json`.

IF `dashboard/traceability-graph.json` exists AND contains `codeRefs` with `origin: "commit-inferred"` or `origin: "task-inferred"`:

1. **Verify commit existence**: For each inferred codeRef with `inferredFrom.commitSha`:
   ```bash
   git cat-file -t <fullSha>
   ```
   If the SHA doesn't exist in the repo, mark as `broken`.

2. **Verify file freshness**: For each inferred codeRef:
   - Check that `file` exists on disk
   - Compare the file's last modification date against the commit date
   - If file was modified AFTER the commit: mark as `stale` (the commit's file list may be outdated)
   - If file was NOT modified: mark as `valid`

3. **Verify task linkage**: For each inferred codeRef with `origin: "task-inferred"`:
   - Check that `inferredFrom.taskId` exists as a defined TASK artifact
   - Check that the TASK has relationships to the `refIds` in the codeRef
   - If the TASK doesn't trace to the claimed refs: mark as `broken`

4. **Compute inference quality**:
   - Inferred refs: valid / stale / broken counts
   - Inference sources: commit-inferred vs task-inferred breakdown
   - Promotion candidates: valid inferred refs that should be promoted to direct `// Refs:` comments
   - Report format: `{ file, symbol, origin, status, inferredFrom, promotionRecommendation }`

5. **Promotion recommendations**: For files with `valid` inferred refs that have been stable for >5 commits:
   - Suggest adding `// Refs: <ids>` comment directly in the source file
   - This promotes the ref from `inferred` to `direct` status

### Step 5.5: Code & Test Chain Verification

Extend the chain to verify CODE and TEST links structurally. This step is **optional** — it runs only when `codeIntelligence` data exists in `dashboard/traceability-graph.json` (generated by `/sdd-code-index`).

IF `dashboard/traceability-graph.json` exists AND contains a `codeIntelligence` block:

1. **Verify codeRef validity**: For each `codeRefs[]` entry across all artifacts:
   - Check that the referenced file exists on disk
   - Check that the symbol still exists at the registered location (file + approximate line)
   - Mark as `valid`, `stale` (file exists but symbol moved/renamed), or `broken` (file missing)

2. **Verify testRef validity**: For each `testRefs[]` entry across all artifacts:
   - Check that the test file exists on disk
   - Check that the named test block exists (search for `it("name"` / `test("name"` / `def test_name`)
   - 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 file:
   - These indicate stale annotations left after spec changes
   - Report: `{ file, line, refId, status: "orphaned" }`

4. **Detect uncovered paths**: Using the call graph from `codeIntelligence.callGraph[]`:
   - Find exported/public symbols reachable from entry points (e.g., route handlers, main exports)
   - Identify those with NO `Refs:` annotation and no inferred refs
   - These are execution paths with no SDD traceability
   - Report: `{ symbol, file, callers, status: "uncovered" }`

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

**Graceful degradation**: If `traceability-graph.json` or `codeIntelligence` not available, skip this step and note "Code intelligence not available — run /sdd-code-index for structural verification" in the report.

### Step 6: Generate Report

```
## SDD Traceability Report

### Summary
- Total defined IDs: X
- Total references: Y
- Orphaned definitions: Z
- Broken references: W
- Coverage: N% of REQs fully traceable
- Commit coverage: N% 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: X/Y (Z%)
- Commits with valid refs: X/Y
- Commits with task trailers: X/Y

#### 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 as above]

### 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 modify any files.
- Be precise with line numbers in reports.
- If a directory doesn't exist, skip it and note it as "not yet generated."
- Tolerate partial pipelines (not all stages may be complete).

---
> Source: [noelserdna/claude-plugin-sdd](https://github.com/noelserdna/claude-plugin-sdd) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->