Should a traceability link attach to a whole requirement, one acceptance criterion, or one scenario?

## Three candidate units A traceability link joins two things, and the interesting choice is the grain of the requirement side. Three units are in common use, and they are not interchangeable. 1. **One link per requirement.** The whole requirement points at a bag of cases. Fast to create, and it is what teams reach for when the record is introduced late. 2. **One link per acceptance criterion.** Each testable statement beneath the requirement points at the checks that verify that statement specifically. 3. **One link per scenario.** Each concrete situation, including the boundary and error variants, gets its own row pointing at the single check that exercises it. ## What each unit makes cheap and expensive | Unit | Cheap | Expensive | |---|---|---| | Whole requirement | Creating links; a small record; almost no upkeep | Saying which promise a failure actually breaks; every failing check implicates the entire requirement | | Acceptance criterion | Reading a failure as a broken promise; naming an unverified statement precisely | Requires criteria that are genuinely written as separate testable statements | | Individual scenario | Knowing exactly which situation is exercised, including boundaries | Row count; churn on every rename; the grain nobody keeps current by hand | The pattern is that cost moves from writing to reading as the unit gets coarser. A whole-requirement link is written in seconds and interrogated forever; a per-scenario link is written a hundred times and answers instantly. ## The year-later read The honest way to choose is to imagine the question somebody asks twelve months on, when the authors have moved and the record is all that is left. - *"We are changing the free-delivery rule. What was promised about it and what checks that promise?"* At requirement grain, the answer is a list of forty cases, most of which have nothing to do with delivery pricing. At criterion grain, it is three rows and the answer is legible in a minute. - *"This check has been failing for a week. What is broken from a user's point of view?"* At requirement grain, the answer is "something in ordering". At criterion grain, it is the sentence the criterion column already holds. - *"Which promises about this feature have never been checked at all?"* At requirement grain this cannot be answered, because a requirement with one linked case looks exactly like a requirement with all of its statements verified. That last one is the decisive argument, and it is why the criterion is the usual answer: a link at requirement grain cannot distinguish partly verified from fully verified, and partly verified is the normal state of real work. ## Choosing, and mixing on purpose The unit should match the unit the promise is made in. If the requirements are written as prose paragraphs with no separable criteria, criterion-grain linking is not available until somebody rewrites them, and pretending otherwise produces invented criteria that nobody accepts. If the requirements already carry numbered acceptance criteria, linking at any coarser grain is throwing away structure that already exists. Mixing grains deliberately is legitimate and is often the right answer. A sensible arrangement: - **Criterion grain by default**, for everything a user or an integrator was promised. - **Scenario grain only where the boundaries carry the risk**: a pricing rule, a permission decision, a state machine with an expensive wrong transition. The extra rows buy something specific there. - **Requirement grain for material that is not really a promise**, such as an internal refactor tracked as a requirement for scheduling reasons only. A useful discipline when writing the link: state, in one sentence, what a failure of this exact link would tell a reader. If the sentence is "something in this area is wrong", the grain is too coarse. If the sentence duplicates the check's own name word for word, the grain is too fine and the row is carrying no information the check did not already carry. ## The practical rule Link at the grain at which somebody would be willing to argue about whether the promise is kept. That is nearly always the acceptance criterion: coarse enough that the row count stays proportional to the promises rather than to the checks, fine enough that a failure names something a person outside the team can understand. Go finer only where the cost of a wrong boundary is high enough to justify the rows, and never go coarser to make the record smaller, because the size the record saves is exactly the information a reader came for.