Traceability

traceability Skill

Generate and validate the requirements-to-evidence traceability matrix for projects that have adopted the regulated-industry track. The skill is the read-mostly counterpart to doc-index: where doc-index builds the catalogue, traceability stitches the catalogue into the audit-facing matrix.

Usage

/traceability                  # Generate matrix and report broken links (warnings only)
/traceability --ci             # Validate-only mode for CI; exits non-zero on broken links
/traceability --check-only     # Validate the existing matrix without regenerating it
/traceability --verbose        # Print per-row resolution detail

No positional arguments. Operates on the current project directory.

Arguments

--ci and --check-only are mutually exclusive. If both are supplied, --ci wins and a warning is printed.

Inputs

Outputs

Both files are regenerated atomically: the skill writes to a sibling *.tmp file and renames on success. A failed generation never produces a half-written artifact.

Opt-in Gate

The skill is purely additive and must not break repos that have not adopted the regulated track.

if [[ ! -f docs/.index/graph.yaml ]]; then
    echo "traceability: docs/.index/graph.yaml absent — skill is a no-op for this repo"
    exit 0
fi

This check runs before any other phase. The exit code is 0 so CI invocations on non-regulated repos do not fail.

Instructions

Phase 0: Validate Environment

1. Confirm docs/.index/graph.yaml exists; if not, print the no-op message and exit 0.
2. Confirm the remaining three index files (manifest.yaml, bundles.yaml, router.yaml) are present. Missing any of these is a hard failure — the matrix cannot be built.
3. Detect optional compliance/ directory at the repo root. Record whether it exists; the clause_refs validation in Phase 3 depends on this.
4. If --check-only is set, skip Phase 1 and 2. Read the existing docs/.index/traceability.yaml directly and proceed to Phase 3.

Phase 1: Resolve Entities

Build in-memory lookup tables from the index files. Reference: reference/matrix-schema.md defines the row shape these tables feed.

1. Requirements: from router.yaml id_routes.SRS, walk each section in section_map and emit one entry per SRS-{CAT}-{NNN} identifier discovered. Record source file and line range for each.
2. Design items: from router.yaml id_routes.SI (and IF if present). Each becomes a candidate design_id for matching requirements.
3. Code paths: from bundles.yaml, collect every files[].file value plus any code_paths field present at the bundle level. The skill does not crawl source-code directories directly — it relies on the bundle catalogue to bound the search.
4. Tests: from router.yaml id_routes.TC. Each TC-{CAT}-{NNN} is a candidate test_id. Section line ranges identify the source SVP document.
5. Risk records: from router.yaml id_routes.H and any id_routes.HUS. Hazards become risk_ids; HUS scenarios are recorded as additional risk evidence.
6. Clauses: if compliance/ exists, scan compliance/*.md for clause anchors. The accepted format is > **Clause**: <STANDARD>-<NUMBER> or a heading ## Clause <STANDARD>-<NUMBER>. Record each clause as {standard, number, file, line}.

Phase 2: Stitch the Matrix

For each requirement_id discovered in Phase 1, build one matrix row by following the cascade graph:

1. Start with the row keyed by requirement_id.
2. Design link: read graph.yaml req_chains.<requirement_category>.design_items and record the matching SI- ids. If the row's requirement_id is SRS-CALC-001, the relevant chain is req_chains.SRS-CALC (or whatever key doc-index produced).
3. Code paths: collect every bundle files[].file whose bundle includes the design id from step 2, or whose bundle name matches the requirement category.
4. Tests: read req_chains.<category>.tests and record matching TC- ids.
5. Risk: read req_chains.<category>.hazards and record matching H- ids.
6. Clause refs: any clauses in compliance/ whose body cites the requirement id (via requirement_id: frontmatter or inline > SRS-<CAT>-<NNN> reference) are added.
7. Status: derive from cell completeness. See reference/matrix-schema.md for the full status table.

Phase 3: Validate

Reference: reference/validation-rules.md defines the broken-link taxonomy and exit codes.

Validation runs whether or not the matrix was just regenerated. Each finding is one of:

Findings are written to the report regardless of mode. The exit-code policy is:

• Default mode: warnings only, exit 0 even when findings exist.
• --ci and --check-only: any finding causes a non-zero exit (see reference/validation-rules.md for the exit-code map).

Phase 4: Write Artifacts

Skip when --check-only is set.

1. Write docs/.index/traceability.yaml.tmp with the row schema from reference/matrix-schema.md.
2. Write docs/.index/traceability.md.tmp from the same row data, formatted as a Markdown table grouped by requirement category.
3. On success, rename both *.tmp files to their final names. On any error, delete the *.tmp files and exit non-zero.

Phase 5: Report

Emit a summary block on stdout:

## Traceability Matrix Generated

| Metric | Value |
|--------|-------|
| Requirements | N |
| Rows complete | N |
| Rows incomplete | N |
| Findings | N (M errors / K warnings) |
| traceability.yaml | X bytes |
| traceability.md | Y bytes |

Append a per-finding table when --verbose is set or when running under --ci.

Output

The skill produces the two artifacts above plus the on-stdout summary. No other files are modified — in particular, the skill never edits manifest.yaml, bundles.yaml, graph.yaml, or router.yaml. Those remain doc-index's responsibility.

Error Handling

Policies

Command-Specific Rules

How Other Components Use the Matrix

References

• Schema for traceability.yaml: reference/matrix-schema.md
• Validation rules and exit codes: reference/validation-rules.md
• Catalogue producer: global/skills/_internal/doc-index/SKILL.md
• Parent epic: kcenon/claude-config#588

Side Effects and Loop-Safety

This skill is loop_safe: true. It is a single-pass (max_iterations: 1) read-mostly operation: it consumes docs/.index/{manifest,bundles,graph,router}.yaml and writes only docs/.index/traceability.{yaml,md}, never mutating source documents. Re-running is idempotent — it regenerates the same two artifacts from current inputs, so wrapping it in a /loop is safe (and a no-op when graph.yaml is absent). The max_iterations: 1 / halt_conditions metadata expresses single-pass exit semantics, not a polling loop.