The Traceability Matrix That Survives a Change Request

What a traceability matrix actually is, one change request walked through it row by row in a quarter of an hour, and the questions it still cannot answer.

Numbers in this note carry source tags ([POLICY], [THREADS n=10], [MINE]). What the tags mean.

The request is one sentence, and it arrives on a Thursday afternoon, because that is when they arrive: can people start a return without uploading a photo?

Nothing in that sentence looks expensive. It takes a step away. It makes the form shorter. In a corridor you would say yes to it in four seconds and mean it.

A traceability matrix is a table that ties each business rule to the requirements that carry it, each requirement to its acceptance criteria, and each criterion to the test that proves it, so that touching any one of them shows you what else has to move. Produced as a deliverable and filed, it is a table nobody opens twice. On a Thursday afternoon it is the difference between an answer and a fortnight of finding out.

The case underneath this is my own: returns and complaints at a mid-size online retailer, built only from the published returns policy, the help centre articles and ten public complaint threads I picked myself. There was no engagement and no client, nobody at that company was interviewed, and nobody there has been asked about anything. The change request above is one I wrote against my own case on purpose, to see what the matrix would catch. Waiting for a real request to find out whether your matrix works means finding out while you are answering it.

In short

• A change request rarely lands on a requirement. It lands on a mechanism, which lives in an acceptance criterion, and the matrix is what walks you from there up to the rule and down to the tests.
• Fifteen minutes of matrix gets you a list of consequences: which criteria die, which tests retire, which get rewritten, which rows are untouched. The untouched ones are half the value.
• The rows worth having are the ones people leave out: rules you inferred rather than read, things you excluded on purpose, and open questions with a due date. A change request reopens exactly those.
• It gives you impact, never judgement. Whether the change is a good idea, what it costs and who will fight it are three other conversations, and the matrix answers none of them.

Where does one sentence actually land?

Here is the part of the matrix the request touches. Six rows, five columns, no tooling.

Set a timer. The walk has four moves and none of them is clever.

Minutes one to three: find the noun

The sentence contains one concrete noun, photo, so that is what I search on. Four rows come back: AC-014-01, the pre-check in REQ-018, the scope exclusion, and OQ-01.

Notice where the request did not land. It never touched a requirement statement. Customers still need their money back for a damaged item, and REQ-014 says so without mentioning a camera. What the request actually edits is the first row: evidence collected before a human sees the case, which is not a published rule at all. It is a design decision of mine, tagged as mine, and the whole to-be stands on it. Ninety seconds in, the shape of the answer has changed: this is not a form tweak, it is a change to the decision the automated pre-check was built around, and that decision has nobody outside the document to confirm it.

Minutes four to seven: read upwards

From the criterion to the requirement to the rule.

AC-014-01 dies outright. There is no upload, so there is no upload limit to test. REQ-014 survives with a smaller criteria set. REQ-018 survives too, and that is the row worth slowing down on: the pre-check reads the delivery date and the order value, neither of which comes from a photograph, so it still approves the easy cases. What changes is the pile it does not approve. Those go to a person with no evidence attached, which puts the judgement the as-is model was criticised for, one agent deciding whether the evidence is enough with no written test, straight back where it was.

Then the answer nobody asks for and everybody wants: AC-014-03 and BR-11 are untouched. The partial refund threshold has nothing to do with photographs, and I can say so with a row behind me instead of a feeling. Naming what does not move is what stops a one sentence request from becoming a full regression pass, and it is the half of impact analysis people skip because it feels like saying nothing.

Minutes eight to eleven: read downwards

Criteria point at tests, and tests are where the estimate lives.

TC-014-01 and TC-014-02 retire. That is the cheap kind of consequence. TC-018-01 is the expensive kind: it does not retire, it gets rewritten, because its precondition assumed a case arrives with evidence attached and now a case can arrive with nothing in it. A test that was passing before the change and passes after it, while checking something different, is the failure mode that survives a whole release. Rewritten tests need a name against them for that reason, and the owner column already has one.

Then the owner column earns its place a second time. Every row that moves is mine, and that is the uncomfortable part rather than the convenient one: the thing this change edits was never published, I decided it, and I have nobody to confirm it with. The published rules in the table, BR-04 and BR-11, do not move at all, and their owner slot has been open since the register was written, OQ-03. In an engagement that sentence names an approver. Here it names an open question, which is the same job done with less authority.

Minutes twelve to fifteen: read sideways

Everything else that points at the evidence decision. This is the move people miss, and it is where the matrix pays for itself.

The scope exclusion is there. Non-delivery and lost parcels were excluded from scope in review, RL-04, and the reason written into the row is that there is nothing to photograph when a parcel never arrives. Make photos optional and that reason evaporates. The request quietly reopens a scope decision that a reviewer forced me to make, and the group it affects is the one least able to argue about it. Without the row, that comes back during build as a defect with somebody's name on it. With the row, it is a line in a Thursday afternoon reply.

OQ-01 shrinks rather than disappearing. Optional photos still means some photos, so the retention question stays open, with a smaller volume behind it and the same due date.

What you can send at the fifteen minute mark

One requirement narrowed, one criterion dead, one requirement whose easy half survives and whose hard half lands back on a person, two tests retired, one test rewritten with a name against it, two published rules confirmed as untouched, one design decision of mine now needing a decision it never had, and one scope exclusion reopened with the reason it was made.

That is a consequence list. It is not a recommendation, and the difference matters when you send it.

What does the matrix refuse to tell you?

This is the part tool guides leave out, and it is the reason a matrix disappoints people who expected more from it.

Whether the change is a good idea. Impact is not judgement. The matrix will walk you cheerfully through a change that halves the evidence quality on every case, and never once suggest that it is a bad trade.

What it costs. Three retired tests and one rewritten one is a shape, not an estimate. The people who build the thing own that number.

Anything that was never written down. A matrix knows the rows you gave it. The coupling in one developer's head, the arrangement agreed verbally, the report somebody built on your data without telling you: none of it is in the table, and reading the table harder will not find it. A matrix reduces surprises, it does not remove them.

Who will object. Consequences do not come with politics attached. The map of who can approve, block or quietly sabotage is a different artifact, and it is one of the six a reader looks for.

Whether the tests are any good. Every row having a test id proves that a link exists. It proves nothing about what the test checks. A matrix with full coverage and weak criteria is a tidy table over a soft product, which is why the criteria have to survive on their own terms before traceability means anything. That standard is a separate piece of work.

Whether it is still true. A matrix last edited three deploys ago is a map of a country that has since moved its roads. It ages faster than any other artifact you keep, because everything else changes underneath it.

The blank version

Copy this. The brackets are the hints, and the last three rows are the ones people delete when they are tidying up, which is exactly when they become useful.

How do you keep one without it becoming a second job?

Five habits, and none of them requires a tool.

One row per criterion. Requirement level rows look tidy and answer nothing, because the mechanism a change request names always sits one level down.

Ids are the product. Renumbering is how a matrix dies. Retire an id, never reuse it, and never renumber to close the gaps.

Edit it in the same sitting as the change. A matrix maintained in a Friday catch-up pass is wrong from Monday to Thursday, which is when the requests arrive.

Keep it in the same file as the register. Two files drift. One file with a table at the end survives handover to someone who has never heard of you.

Mark inference on the face of the row. Published rules and your own decisions behave differently under a change request, as BR-11 and the evidence decision did above, and you will not remember which was which in six weeks.

Take one requirement you already have and write its row: rule, criterion, test, owner, sources named. Then write a one sentence change request against it, the kind that would arrive on a Thursday, and time yourself walking it through. If the walk takes longer than a quarter of an hour, the missing pieces are the columns you skipped.

Traceability is check 01 in the scorecard, which is twenty-five checks you can run on your own case before anybody else runs them on you.

All field notes · The portfolio guide · More in Requirements That Survive Review