Tracing Requirements To Code

Tracing Requirements to Code

Use this skill when the tests already exist and the question is what they actually verify.

Traceability is usually taught forward: take a specification, derive requirements, plan tests. That is requirements-test-coverage-mapper, and it is the right skill when you start from a document. This skill handles the other and more common situation: a live codebase, hundreds of tests, requirements scattered across a tracker and three documents, and no reliable statement of which test proves what.

The insistence that makes this worth doing: a traceability link is a claim, not a record. A test tagged @req REQ-014 claims to verify REQ-014, and nothing about writing the tag makes that true. An unverified matrix is worse than no matrix, because it converts ignorance into documented confidence, and it is exactly the artifact people reach for when deciding what not to test.

When to Use

• a suite exists and nobody can say which requirement a given test serves
• someone asks "which tests cover this requirement" and the answer takes a day
• a matrix was built once, was accurate that week, and has not been true since
• a requirement is changing and its affected tests must be found
• tests exist that nobody can trace to any requirement
• an audit, certification, or customer questionnaire needs coverage evidence

Operating Principles

• Traceability runs both ways. Requirement to test finds coverage gaps. Test to requirement finds orphan tests, and nobody looks in that direction.
• A link is verified or it is a guess. The test must fail when the requirement's behaviour is broken. Until it has been seen to, the link is unconfirmed and labelled as such.
• Extract from evidence, not from titles. A test called "validates the discount rule" is a hypothesis about what it does. The assertions are the evidence.
• The matrix lives in the code, not in a spreadsheet. A link stored beside the test moves when the test moves. A link in a document rots the first time anyone refactors.
• Orphans are findings in both directions. An uncovered requirement is a coverage gap. An orphan test is either an undocumented requirement or a test of nothing, and both are worth knowing.
• Drift is the default. Links rot silently through renames, deletions, and refactors. Without a CI check, the matrix is accurate on the day it is written and decreasingly true afterwards.

Workflow

Phase 0: Establish the requirement source

Before touching tests, fix what a requirement is in this project and where the authoritative list lives:

• an issue tracker with stable keys (PROJ-1234)
• acceptance criteria inside stories
• a PRD or specification document
• a regulatory or contractual requirement list
• none of the above, in which case the first deliverable is a requirement inventory derived from the code and the tracker, marked as derived rather than authoritative

Record the ID scheme, and whether IDs are stable. An ID that changes when a ticket moves project is not usable as a link target, and discovering that after annotating 400 tests is expensive.

./resources/id-and-annotation-conventions.md covers choosing a scheme that survives.

Phase 1: Extract what the tests actually verify

Work through ./resources/extracting-an-rtm.md. The method, in short:

1. Inventory the tests. Every test, its file, its title, its level.
2. Read the assertions, not the titles. What behaviour would have to break for this test to fail?
3. Group by behaviour, not by file. Several tests often serve one requirement, and one god test sometimes serves five.
4. Map to requirements where the mapping is defensible.
5. Label the confidence of each mapping: stated (the test or its commit names the requirement), inferred (the behaviour clearly matches), guessed (it plausibly relates).

Do not silently promote a guess. A matrix that distinguishes stated from guessed is honest and usable; one that flattens them is a document nobody should trust and everybody will.

Phase 2: Annotate at the source

Move each defensible link into the code, next to the test it describes.

test('rejects a card that expired last month @req:REQ-014', async ({ page }) => { ... });

Per-runner spellings, the machine-readable formats, and the trade-offs between tags, annotations, and comments are in ./resources/id-and-annotation-conventions.md.

Rules that decide whether this survives:

• one canonical form, chosen once and used everywhere, so a generator can parse it
• machine-readable, because a convention nothing checks is a convention that decays
• at the test level, not the file level, unless every test in the file genuinely serves the same requirement
• many-to-many is normal: one test may serve several requirements and one requirement needs several tests

Phase 3: Verify the links

The phase that separates this from bookkeeping. For each link, and at minimum for every link on a high-risk requirement:

1. Break the behaviour the requirement describes.
2. Run the linked test.
3. Confirm it fails, and that the failure names something recognizable.
4. Record the link as verified with the date.

A link that survives step 3 with a passing test is a false claim in the matrix. Fix the test or remove the link; do not leave it as documented coverage.

This is the same standard unslop-tests and migrating-tests-to-playwright apply, for the same reason: a test that has never been observed failing has unmeasured value, and a matrix built on such tests inherits that.

Verifying every link in a large suite is not affordable. Verify by risk, record the coverage of the verification itself, and state what was taken on trust.

Phase 4: Find the orphans

Cross the two directions and take all four quadrants seriously. ./resources/orphan-and-drift-detection.md has the triage.

• Coverage gap: a requirement nothing verifies. Route to designing-functional-tests or requirements-test-coverage-mapper.
• Orphan test: the direction nobody looks. It is one of three things, and the distinction matters:
  • an undocumented requirement, which is the valuable case. The behaviour matters, someone tested it, nobody wrote it down. Write it down.
  • a test of a removed feature, which should be deleted.
  • a test that proves nothing, which unslop-tests should judge.

Reporting orphan tests as a single count wastes them. Classify each one.