SuperAPI AI Directory
Partner中文AI newsFavorites
Skills09-traceability-engineering

09-traceability-engineering

Office & productivity

View repository

Updated 10-16 03:40

About this skill

Traceability Engineering Skill Guidance

Use When

  • establishing forward and backward links among goals, requirements, design, code, tests, and evidence; use traceability-matrix for the governance roll-up artefact.
  • Use this procedure when the required source artefacts are available and Trace model and gap register is the next lifecycle deliverable.

Do Not Use When

  • Use traceability-matrix when that neighbouring route owns the decision or deliverable.
  • Do not invent missing project evidence, standards clauses, thresholds, or stakeholder decisions.

Required Inputs

Artefact Source or provider Required? Behaviour when missing
Stable identifiers and approved lifecycle artefacts Phase owners and project registries Yes Stop the affected step, name the missing source, and return only a qualified gap record.

Workflow

  1. Inspect the required inputs and log the exact sources, versions, and unresolved assumptions.
  2. Apply this skill's existing domain workflow and decision rules to produce Trace model and gap register.
  3. Stop when a required source, accountable decision owner, or deterministic test oracle is absent.
  4. Recover by preserving valid work, marking the blocked scope, and returning the narrowest qualified artefact plus the next evidence needed.

Outputs

Artefact Consumer Acceptance condition
Trace model and gap register Requirements management, design, testing, and governance Required sections are populated, source links resolve, and every material requirement or decision has an observable review or test oracle.

Evidence Produced

Evidence Reviewer Acceptance condition
Source, decision, trace, and validation record for Trace model and gap register Requirements quality reviewer Inputs used, decisions made, checks run, failures, and unassessed items are explicit.

Capability and permission boundaries

Read and search are required. Editing is allowed only when the request authorises creation or repair of the named requirements artefact. Publishing, production mutation, destructive action, spending, and certification require explicit authority.

Degraded mode

Fallback: if a required file, reviewer, standard source, network check, renderer, or execution capability is unavailable, return the narrowest useful qualified result and mark the affected check not assessed; never convert an unassessed check into a pass.

Decision Rules

Choice or condition Action Failure or risk avoided
A source or target has no stable identifier Stop the link operation and assign or reconcile the identifier first. False coverage and orphaned lifecycle evidence.
Required inputs and test oracles are complete Continue through the existing workflow and record evidence. A deliverable whose acceptance cannot be reproduced.
A mandatory source or owner is missing Stop the affected branch and issue a qualified gap record. Fabricated context or unauthorised decisions.

Quality Standards

  • Preserve stable identifiers and bidirectional traceability from project evidence to Trace model and gap register and its acceptance checks.
  • Apply ISO/IEEE measures only with a named metric, method, threshold, evidence source, and responsible reviewer; run the anti-slop gate before release.

Anti-Patterns

  • Producing Trace model and gap register from assumed context. Fix: cite the project source or mark the scope blocked.
  • Accepting a material requirement without a deterministic oracle. Fix: add a measurable result, boundary, and verification method.
  • Crossing into traceability-matrix without routing the decision. Fix: hand off the named input and preserve trace links.
  • Treating an unavailable check as passed. Fix: mark it not assessed and state the release consequence.
  • Claiming standards, statutory, or stakeholder approval without evidence. Fix: cite the source and reviewer or qualify the claim.

References

Book-informed practice route

Use the scenario-spine and requirement-contract reference for scenario-to-requirement-to-test-to-evidence links.

Overview

Run this skill after requirements have been baselined and validated. It builds a four-level trace chain linking every requirement to its originating business goal, downstream design element, and verification test case. The skill detects orphan requirements, gold-plating, and coverage gaps, producing a comprehensive traceability matrix that serves both Waterfall auditing and Agile quality gates.

When to Use This Skill

  • After 08-requirements-management has established a baseline.
  • When preparing for design phase handoff to ensure all requirements are traceable.
  • As a quality gate before development begins.
  • During audits to demonstrate requirements coverage and accountability.
  • As an Agile quality gate to verify user stories trace to business goals.

Quick Reference

  • Inputs: projects/<ProjectName>/_context/vision.md, projects/<ProjectName>/_context/stakeholder_register.md, all projects/<ProjectName>/<phase>/<document>/ artifacts
  • Outputs: projects/<ProjectName>/<phase>/<document>/traceability_matrix.md
  • Tone: Analytical, systematic, gap-focused

Input Files

File Source Required?
vision.md projects/<ProjectName>/_context/ Yes
stakeholder_register.md projects/<ProjectName>/_context/ Yes
All *.md artifacts projects/<ProjectName>/<phase>/<document>/ Yes
requirements_baseline.md projects/<ProjectName>/<phase>/<document>/ Recommended

Output Files

File Contents Destination
traceability_matrix.md Four-level trace matrix with gap analysis and coverage metrics projects/<ProjectName>/<phase>/<document>/

Core Instructions

Step 1: Read All Inputs

Read projects/<ProjectName>/_context/vision.md, projects/<ProjectName>/_context/stakeholder_register.md, and every artifact in projects/<ProjectName>/<phase>/<document>/. Log each file path read. Extract:

  • Business Goals: From vision.md -- assign identifiers (BG-001, BG-002, ...) if not already present.
  • Requirements: From all output artifacts -- collect every requirement ID (REQ-xxx, FR-xxx, NFR-xxx, US-xxx).
  • Design Elements: From any design or architecture artifacts -- assign identifiers (DE-001, DE-002, ...) if present.
  • Test Cases: From any test artifacts -- collect test case IDs (TC-001, TC-002, ...) if present.
  • Stakeholders: From stakeholder_register.md -- map each requirement to its source stakeholder.

Step 2: Define Trace Link Types

Establish the following trace link taxonomy for all connections in the matrix:

Link Type Direction Description
derives-from Requirement -> Business Goal Requirement originates from a business goal
satisfies Design Element -> Requirement Design element fulfills a requirement
implements Code Component -> Design Element Code realizes a design element
verified-by Requirement -> Test Case Test case validates a requirement
conflicts-with Requirement <-> Requirement Two requirements contradict each other
refines Requirement -> Requirement Detailed requirement elaborates a parent
replaces Requirement -> Requirement New requirement supersedes an old one

All links shall be maintained bidirectionally: if REQ-001 derives-from BG-003, then BG-003 shall list REQ-001 as a derived requirement.

Step 3: Build Four-Level Trace Chain

For every requirement, establish the complete trace chain:

Business Goal (BG-xxx)
  -> Requirement (REQ-xxx) [derives-from]
    -> Design Element (DE-xxx) [satisfies]
      -> Test Case (TC-xxx) [verified-by]

For each requirement, record:

Field Description
Req ID Unique requirement identifier
Business Goal BG-xxx that this requirement derives from
Source Stakeholder Stakeholder who originated or owns the requirement
Design Element DE-xxx that satisfies this requirement (if available)
Test Case ID TC-xxx that verifies this requirement (if available)
Trace Status Complete, Partial, Orphan, or Untested

Step 4: Detect Orphan Requirements

An orphan requirement has no upward trace link to a business goal. For each orphan:

  1. Tag the requirement with [TRACE-GAP].
  2. Record the gap type: "No business goal linkage."
  3. Recommend action: link to an existing goal, create a new goal, or retire the requirement.

Step 5: Detect Gold-Plating

Gold-plating occurs when a design element or feature exists without a corresponding requirement. For each instance:

  1. Tag the element with [TRACE-GAP].
  2. Record the gap type: "Design element without requirement justification."
  3. Recommend action: create a requirement to justify the element, or remove the element.

Step 6: Detect Untested Requirements

An untested requirement has no downward trace link to a test case. For each instance:

  1. Tag the requirement with [TRACE-GAP].
  2. Record the gap type: "No test case linkage."
  3. Recommend action: create a test case with verifiable acceptance criteria.

Step 7: Calculate Traceability Coverage

Compute the following coverage metrics:

$$\text{Upward Coverage} = \frac{\text{Requirements with Business Goal links}}{\text{Total Requirements}} \times 100$$

$$\text{Downward Coverage} = \frac{\text{Requirements with Test Case links}}{\text{Total Requirements}} \times 100$$

$$\text{Full Coverage} = \frac{\text{Requirements with both BG and TC links}}{\text{Total Requirements}} \times 100$$

$$\text{Design Coverage} = \frac{\text{Requirements with Design Element links}}{\text{Total Requirements}} \times 100$$

Step 8: Detect Conflicts

Scan all requirements for contradictions. Two requirements conflict when they specify mutually exclusive behaviors for the same system element. Tag each conflict pair with [TRACE-GAP] and record:

  • Conflicting requirement IDs.
  • Nature of the conflict.
  • Recommended resolution.

Step 9: Generate Output

Write projects/<ProjectName>/<phase>/<document>/traceability_matrix.md following the output format below.

Output Format

traceability_matrix.md

# Traceability Matrix: [Project Name]

**Generated:** [Date]
**Baseline:** BL-[PROJECT]-[VERSION]
**Standards:** IEEE 1012-2016, IEEE 29148-2018

---

## Coverage Summary

| Metric | Value | Threshold | Status |
|--------|-------|-----------|--------|
| Upward Coverage (BG links) | N% | >= 85% | [PASS/FAIL] |
| Downward Coverage (TC links) | N% | >= 85% | [PASS/FAIL] |
| Full Coverage (BG + TC) | N% | >= 70% | [PASS/FAIL] |
| Design Coverage (DE links) | N% | >= 60% | [PASS/FAIL] |
| Orphan Requirements | N | 0 | [PASS/FAIL] |
| Gold-Plated Elements | N | 0 | [PASS/FAIL] |
| Conflicts Detected | N | 0 | [PASS/FAIL] |

---

## Trace Matrix

| Req ID | Title | Business Goal | Stakeholder | Design Element | Test Case | Status |
|--------|-------|---------------|-------------|----------------|-----------|--------|
| REQ-001 | ... | BG-001 | [Name] | DE-001 | TC-001 | Complete |
| REQ-002 | ... | [TRACE-GAP] | [Name] | DE-002 | TC-002 | Orphan |

---

## Gap Analysis

### Orphan Requirements (No Business Goal)

| Req ID | Title | Recommended Action |
|--------|-------|--------------------|
| REQ-002 | ... | Link to BG-003 or retire |

### Untested Requirements (No Test Case)

| Req ID | Title | Recommended Action |
|--------|-------|--------------------|
| REQ-005 | ... | Create TC with acceptance criteria |

### Gold-Plated Elements (No Requirement)

| Element ID | Description | Recommended Action |
|------------|-------------|--------------------|
| DE-007 | ... | Create requirement or remove element |

### Requirement Conflicts

| Req A | Req B | Conflict Description | Recommended Resolution |
|-------|-------|---------------------|----------------------|
| REQ-003 | REQ-012 | ... | ... |

---

## Trace Link Summary

| Link Type | Count |
|-----------|-------|
| derives-from | N |
| satisfies | N |
| verified-by | N |
| conflicts-with | N |
| refines | N |
| replaces | N |

Common Pitfalls

  • Shallow tracing: Linking requirements only to goals but not to test cases creates a false sense of coverage. Always build the full four-level chain.
  • Missing bidirectional maintenance: If a forward link exists (REQ -> TC), the reverse link (TC -> REQ) must also be maintained. One-way links break audit traversal.
  • Ignoring non-functional requirements: NFRs are often excluded from trace matrices. Every NFR shall have a business goal link and a verification method.
  • Stale links: When requirements change, trace links become outdated. Re-run this skill after every baseline update.
  • Over-counting conflicts: Distinguish genuine contradictions from complementary requirements that address different scenarios of the same feature.

Verification Checklist

  • Every requirement has been evaluated for upward (BG) and downward (TC) trace links.
  • Orphan requirements are tagged with [TRACE-GAP] and have recommended actions.
  • Gold-plated design elements are identified and tagged.
  • Coverage percentages are calculated for all four metrics.
  • Conflicts are documented with resolution recommendations.
  • All trace links use the defined link type taxonomy.
  • Bidirectional link integrity is maintained.

Integration

  • Upstream: 08-requirements-management, all specification and validation skills
  • Downstream: 10-requirements-metrics, waterfall/08-semantic-auditing
  • Complements: waterfall/08-semantic-auditing (RTM section); this skill produces a standalone, enhanced trace matrix

Standards

  • IEEE Std 1012-2016: Software Verification and Validation -- traceability analysis.
  • IEEE Std 29148-2018: Requirements engineering -- traceability provisions.
  • Laplante Ch.7.3: Requirements traceability matrices and coverage analysis.
  • Wiegers Practice 18: Requirements traceability and link management.
  • IEEE Std 610.12-1990: Terminology definitions.

Resources

  • references/trace-matrix-template.md: Traceability matrix template and usage guide.
  • references/trace-link-types.md: Trace link taxonomy and bidirectional maintenance rules.
  • Java enterprise requirements overlay: trace Java requirements through implementation, tests, migrations, release evidence, telemetry and runbook ownership.

Last Updated: 2026-03-07 Skill Version: 1.0.0