Proof · Engineering practice
Requirements traceability matrix: example and template
A requirements traceability matrix (RTM) links each requirement to its source, implementation and verification. It helps you find missing coverage and assess change impact. Include the revision and observed result so a link to a test cannot be mistaken for a passing check.
Free matrix template and filled example
A requirements list records the promises. A traceability matrix connects them to the artifacts that justify, implement and check those promises. You can start in a spreadsheet; the important part is maintaining the relationships and their revisions.
Open the CSV in Excel, or import it into Google Sheets with a comma separator. Each row connects one requirement to one check, so several rows may share a requirement ID. The blank file has 19 columns covering intent, implementation, execution and the next action. No signup needed.
Blank matrix (.csv) · Filled illustrative matrix (.csv)
The filled file uses the session-timeout example below. Its observations are illustrative, and its output links are deliberately empty. Replace them with your own records. For a document or issue tracker, use the copyable record instead.
Repeat this record for each requirement and verification relationship. Requirement ID and revision: Statement and acceptance condition: Source or parent requirement: Approval state and responsible owner: Implementing component and code reference: Candidate code revision: Verification method and check ID: Run ID, checked revision and environment: Expected observation: Actual observation and output link: Evidence state: missing / current / stale / inconclusive Observed outcome, if executed: pass / fail Gap, next action and owner: Reason to recheck:
Forward tracing follows a requirement into implementation and checks. Backward tracing asks which requirement justifies a piece of code or a check. Bidirectional traceability supports both questions. A test can cover several requirements, and a requirement can need several checks.
Keep the result next to the link
Use a row like this when a session timeout changes from 30 to 15 minutes. The identifiers and observations below are illustrative. The candidate is code revision B; the approved timeout requirement is revision 2.
| Requirement and revision | Implementation and check | Evidence at candidate B | Next action |
|---|---|---|---|
| SYS-REQ-870 r2: expire an idle session after 15 minutes. | session.go; TestIdleTimeout | STALE: the linked pass checked r1 and code A at 30 minutes. | Run boundary cases against r2 and B; retain the old result as history. |
| SYS-REQ-879 r1: active use renews the idle timer. | session.go; TestActivityRenews | MISSING: a test is linked, but no result is recorded for B. | Execute it and inspect whether it checks renewal rather than merely login. |
| SYS-REQ-881 r1: explicit logout revokes the session. | logout.go; TestLogoutRevokes | CURRENT IN THIS EXAMPLE: a linked result at B checks revocation. | Inspect its inputs and scope; it does not establish the other two rows. |
A minimal reusable row needs the requirement revision, code revision, implementation target, check, observed result, output link and reason to recheck. Keep “not run” separate from “failed.” A new result should supplement the history, not overwrite which revision the old pass described.
How to build and maintain the matrix
- Choose a bounded scope. Name the component, release and requirement inventory. List exclusions.
- Identify the promises. Give each requirement a stable ID and revision; keep candidate intent visibly unapproved.
- Connect implementation and checks. Record the real relationship, not merely a shared keyword.
- Attach observations. Keep the checked revision, conditions, outcome and producing artifact.
- Investigate gaps. Missing links, unexecuted tests and failed results need different actions.
- Review each change. Follow affected relationships and renew evidence whose basis changed.
For an agent-written change, use the matrix to ask which existing promises the prompt did not mention. The AI-code verification guide shows how to turn that into a review of the actual candidate.
Two requirement-link directions must agree
Illustrative example: stakeholder requirement STK-REQ-004 requires session timeout after inactivity. Its acceptance criterion names SYS-REQ-870, while another system requirement, SYS-REQ-879, also claims to satisfy that stakeholder requirement.
| Relationship | Recorded value | Result |
|---|---|---|
| Parent acceptance criterion | derived_reqs: SYS-REQ-870 | SYS-REQ-879 is omitted from the parent’s criterion lists. |
| SYS-REQ-870 | satisfies: STK-REQ-004 | Listed in both directions. |
| SYS-REQ-879 | satisfies: STK-REQ-004 | Inverse coverage reports a requirement-link mismatch. |
proof audit --check spec_lint_ac_subset_of_satisfies \
--check spec_lint_ac_inverse_coverage
The subset check asks whether each cited child exists and has the expected traces.satisfies back-link. The inverse check asks whether active system children that satisfy a stakeholder requirement with acceptance criteria appear in those criteria’s derived_reqs. Both compare authored requirement data. They do not inspect session.go, resolve a source symbol or execute a timeout test.
Check source and evidence separately
After repairing the mismatch, inspect the implementation and test targets. These examples assume the named files and test belong to the project:
proof trace show SYS-REQ-870
proof trace suspect
test -f internal/session/session.go
go test ./internal/session -run TestIdleTimeout -count=1
trace show displays the recorded links. trace suspect identifies changes against recorded trace-review fingerprints. The shell check above establishes file existence only; inspect any referenced symbol as well. The Go command selects the named test in one package. Confirm the test actually ran: a command that reports no matching tests is not a passing witness. Its assertion, inputs, environment and output determine what behavior the result supports.
A fingerprint change asks for review, not an automatic conclusion that behavior is wrong. A fresh review stamp is also not a replacement for executing the affected test. Retain the target revision and the producing test result.
Keep the source of each relationship clear
Requirements-management tools can version artifacts, maintain traceability and integrate with engineering systems. Whether their links stay useful depends on the configured integrations and review process. A hand-maintained spreadsheet can drift, but that is not a universal limitation of every requirements product.
Proof keeps requirements, code references, hazards and evidence in a graph that agents and reviewers can inspect. Recovered requirements remain candidates until their authority is resolved. When an obligation changes, preserve its previous revision and reconsider dependent requirements and evidence.
NASA’s SWE-052, Bidirectional Traceability specifies relationships among software requirements and other engineering artifacts, with applicability differing by software class. A consistent matrix alone does not establish compliance or correct behavior. Source checked 2 October 2026.
State which set the matrix covers
A complete matrix can omit a promise nobody recorded or a code path nobody linked. Define the requirement inventory, code scope and exclusions before reporting coverage. Review orphan artifacts for whether they reveal missing requirements, extra functionality or stale records.
Continue with coverage denominators and the evidence needed for each requirement.
Find the gaps around one real change
Bring a requirement set, a proposed change and the checks you already run. We can scope an audit of missing links, stale results and behavior that still needs evidence, alongside your existing development process.