sdlc-requirements-traceability

name	sdlc-requirements-traceability
description	Use to build or audit RTM links across requirements, design, validation, tasks, PRs, commits, releases, and evidence gaps.
metadata	{"version":"0.5","updated":"2026-07-26"}

Requirements Traceability

Use this workflow to create, update, or inspect a requirements traceability matrix.

Traceability connects intent to execution:

Business / User / Product / Software Requirement
-> HLD / LLD / ADR / Domain Boundary / SPEC / Validation Plan / Handoff / Task
-> Test / Review / PR / Release

Traceability is strongest when SDLC materials exist. When no SDLC materials exist, traceability can still start from an issue, bug report, task ID, test failure, or direct-dev handoff. Do not block small development work solely because a full RTM is absent; create a traceability seed and mark the evidence level.

For lightweight SDLC-ADS work, use the operating-model contract as the default:

REQ -> TASK -> VAL
ARCH / DOM / DEC -> TASK
ITEM -> TASK / VAL / Q

Do not require BRD/URS/PRD/SRS prefixes before a clear direct-dev, handoff-lite, or refactor task can proceed.

Use when

• Requirements, specs, tasks, tests, PRs, or release notes must be connected.
• A feature has BRD, URS, PRD, SRS, NFR, HLD, LLD, ADR, Domain Boundary Map, SPEC, Validation Plan, or dev handoff artifacts.
• Work spans multiple tasks, modules, agents, or validation paths.
• You need to detect orphan requirements, orphan tasks, missing tests, or untracked changes.
• A change request modifies a prior requirement baseline.
• Dev needs requirement IDs to reference in task cards, commits, PRs, or review notes.

Do not use when

• The task is a small direct code change with no need for formal tracking beyond issue and validation notes.
• The user only asks to implement, debug, test, or review code.
• No stable source material exists and the immediate task is safe to route to dev; create a task handoff instead.
• The request is to approve scope or release readiness. Recommend $codex-next:sdlc-readiness-review or use dev-release-check as appropriate.

Inputs

Use what exists. Do not require all artifact families.

Source artifacts

• BRD or business brief
• URS or user scenarios
• PRD or product requirements
• NFR matrix
• SRS
• HLD
• LLD
• ADR
• Domain Boundary Map
• SPEC slices
• validation plan, acceptance test matrix, smoke checklist, regression scope, or evidence expectations
• solution spec
• change control record

Execution artifacts

• dev handoff
• task cards
• issue tracker items
• test plan or test cases
• validation command logs
• PRs, commits, branches, or release notes
• bug reports or incidents

Direct-dev traceability sources

When SDLC artifacts are absent, trace from:

• issue ID
• bug ID
• user request
• reproduction step
• failing test
• file path or symbol
• task handoff ID

Workflow

1. Choose traceability depth

Use the depth that matches the lane and risk.

Depth	Use when	Matrix shape
seed	direct-dev, issue-backed, bugfix, early draft	Source -> TASK -> VAL
standard	contained feature delivery	REQ -> TASK -> VAL -> Test
architecture	architecture/domain-sensitive delivery	REQ + ARCH/DOM/DEC -> TASK -> VAL -> Test
extended	system, rebuild, multi-wave, or release-bound delivery	REQ + ARCH/DOM/DEC -> TASK -> VAL -> Test -> PR -> Release
audit	baseline, compliance, high-risk, or release-bound evidence	Same chain plus owner, status, evidence, change record

Do not force extended or audit depth on every change.

2. Inventory source IDs

Collect stable IDs from available artifacts.

Use these prefixes:

Prefix	Meaning
REQ	Requirement from requirements package or scope decision table
DEC	Durable decision
ARCH	Architecture constraint
DOM	Domain, ownership, data, or dependency constraint
TASK	Dev task
VAL	Validation item
Q	Open question or blocker
ITEM	Midstream intake item

If an input has no ID, create a lightweight local ID and mark it as generated. Use only the prefixes above.

3. Normalize requirement rows

Each row should represent one traceable item or one traceable chain.

Base columns:

| Trace ID | Source | Requirement | Type | Priority | Downstream | Task | Validation | Status |
|---|---|---|---|---|---|---|---|---|

Extended columns:

| Trace ID | Source | REQ | ARCH/DOM/DEC | TASK | VAL | Test | PR/Commit | Release | Owner | Status | Evidence | Change |
|---|---|---|---|---|---|---|---|---|---|---|---|---|

Use compact rows. A traceability matrix should help dev and review, not become an unreadable archive.

4. Link source to software-facing requirements

Map source materials to REQ, TASK, and VAL.

Examples:

REQ-001 -> TASK-001 -> VAL-001
ARCH-001 -> TASK-002
DOM-001 -> TASK-003
Issue-123 -> TASK-001
Bug-456 -> TEST-REG-001

Rules:

• One upstream item may map to several downstream requirements.
• One downstream task may satisfy several requirements only if the task scope is still coherent.
• Mark inferred links explicitly.
• Do not hide many-to-many relationships by collapsing unrelated items.

5. Link requirements to architecture/domain artifacts and SPEC slices

For each REQ or task item, identify needed architecture/domain and specification evidence:

Requirement	Needed architecture/domain constraint	Needed specification detail	Status
REQ-001	ARCH-001, DOM-001, DEC-001	20-规格.md API section	present / missing / not applicable

If no specification detail is required, state why. If no HLD, LLD, ADR, or Domain Boundary Map is required, state why when the work is architecture-sensitive.

6. Link validation plan to tasks and tests

Each implementation task should have a validation path. When a Validation Plan or acceptance matrix exists, link tasks to the relevant validation IDs before linking to executed test evidence.

Task	Validation Plan item	Test or check	Type	Status
TASK-001	VAL-001	pytest path/test_name	unit / integration / e2e / manual / smoke / NFR	planned / passed / failed / not run

Do not mark validation as passed unless evidence exists.

7. Record execution evidence when available

When dev has started or finished, add:

• branch name
• PR number or link
• commit SHA if relevant
• test command and result
• review verdict
• release or deployment reference

If execution evidence is not yet available, leave it blank or mark pending.

8. Detect traceability gaps

Report gaps by type:

Gap	Meaning
orphan source	requirement has no downstream SRS/task
orphan task	task has no source or issue link
missing validation	task or requirement has no test/validation
missing validation plan	feature, system, release, NFR, architecture, or domain-sensitive work lacks explicit proof-of-correctness plan
missing SPEC	requirement needs UI/API/Data/etc. spec but none exists
missing architecture artifact	requirement needs HLD, LLD, ADR, Domain Boundary Map, or Directory SPEC but none exists
boundary conflict	task or SPEC appears to violate ownership, dependency, or forbidden access rules
stale link	target artifact is superseded
unapproved change	task implements changed scope without change record
direct-dev risk	implementation proceeds from issue/task without formal SDLC materials

Not every gap blocks dev. Classify severity:

blocker
important
watch
accepted

9. Support direct-dev traceability

For a direct-dev task, produce a seed matrix:

| Trace ID | Source | Task | Validation | Risk | Status |
|---|---|---|---|---|---|
| TRACE-001 | Issue-123 | TASK-001 | pytest path/test_name | low | planned |

This preserves evidence without pretending a full SDLC chain exists.

Output

Return or write one of these outputs.

Traceability seed

# Traceability Seed: <Change Name>

| Trace ID | Source | Task | Validation | Risk | Status |
|---|---|---|---|---|---|

Standard RTM

# Requirements Traceability Matrix: <Feature / System>

## 1. Scope
## 2. Artifact Sources
## 3. Traceability Matrix
## 4. Gap Report
## 5. Execution Evidence
## 6. Change Notes

Gap report

# Traceability Gap Report

## Blocking gaps
## Important gaps
## Accepted gaps
## Recommended next action

Validation

Before declaring traceability ready, check:

• Every P0/P1 SRS requirement has a downstream task or explicit deferment.
• Every implementation task has a source or direct-dev source note.
• Every requirement or task has a validation plan or explicit accepted gap.
• NFRs have validation methods, not only statements.
• Validation Plan items link to tasks and execution evidence where a validation plan exists.
• Architecture-sensitive requirements point to HLD, LLD, ADR, Domain Boundary Map, or an explicit accepted gap.
• SPEC-dependent requirements point to the relevant SPEC slice or missing-SPEC gap.
• Change-related rows point to existing change-control records when baseline is affected.
• Status values are consistent.
• Direct-dev work is not misrepresented as full SDLC-backed work.

Boundaries

• Do not approve requirements.
• Do not execute tests or claim validation success without evidence.
• Do not block safe direct-dev work solely because a full matrix is absent.
• Do not create fake BRD, URS, PRD, SRS, or SPEC IDs to make the matrix look complete.
• Do not use traceability as a substitute for sdlc-dev-handoff-planning.
• Do not overwrite existing tracking conventions without user approval.

Handoff

Recommend the smallest next step. For an explicit-control workflow, return its exact $codex-next:<skill-name> command and stop; do not begin it here.

Route findings:

Finding	Next step
source not ready	$codex-next:sdlc-requirements-workflow, sdlc-prd-workflow, or sdlc-srs-workflow
HLD missing	sdlc-hld-workflow
LLD missing	sdlc-lld-workflow
ADR missing	sdlc-architecture-decision-record
domain boundary missing	sdlc-domain-boundary-modeling
SPEC missing	sdlc-spec-slice-writer
validation plan missing	sdlc-validation-plan-workflow
handoff missing	sdlc-dev-handoff-planning
baseline changed	$codex-next:sdlc-change-control
readiness uncertain	$codex-next:sdlc-readiness-review
implementation ready	dev skill such as dev-spec-driven-implementation, dev-bugfix, or dev-test-strategy
direct-dev safe but untracked	create traceability seed and proceed to dev