Should a traceability record be generated from links in the work, or maintained as its own document?

## Two ways to produce the same table The same rows can be produced in two very different ways, and the choice determines what the result can be asked and what it costs to keep. **Derived (generated).** Nobody writes the table. Each work item, case, change and defect record already carries a reference field, and the table is a query over those fields, run when someone wants to look. The record has no existence between readings. **Authored (maintained).** Somebody writes and edits a document whose rows mirror the work. It exists as a file with a version history, and it says what its last editor said. ## What each can be asked to show | Question | Derived | Authored | |---|---|---| | Which checks name this criterion? | Yes, from the reference fields | Yes, as of the last edit | | What did each check last do, and on which build? | Yes, from stored results | Only if somebody copied it in | | Is this row current? | Trivially: it was computed just now | Unanswerable from the document itself | | Why was partial verification accepted here? | No: the work stores no such field | Yes, that is what free text is for | | What did we claim on the day we shipped? | Only if the query is snapshotted and kept | Yes, that is what a version history is | | What changed in the record since last month? | Only by comparing two snapshots | Yes, from the edit history | The rule underneath the table is short: **a derived record can show exactly the facts the work stores, and nothing else; an authored record can show anything and vouches for nothing.** Most of what people want from the record is in the first category, which is why derivation is the default answer. The exceptions are judgements, and judgements are the reason an authored column survives at all. ## Cost profiles Derived costs are **up front and structural**: stable identifiers, a reference field that is actually required, and one query to write. After that, producing the record is free, and it is free again tomorrow. The failure mode is not staleness but silence: a criterion nobody referenced simply does not appear as verified, which is honest but only useful if somebody looks. Authored costs are **per change and permanent**: every renamed case, every new result, every added criterion is a manual edit, and the edits are cheapest to skip when the delivery is busiest. The failure mode is a document that reads confidently and describes last month. ## Where the link lives, and who reads it there The two arrangements differ in a way that has nothing to do with the table and everything to do with attention. Where the link is **a field on the work item itself**, it sits in front of every person who opens that item for any reason, so a wrong or missing reference is spotted incidentally by whoever is doing the next piece of work. Where the link set is **a separate document**, it is read on purpose, by the small number of people whose job brings them to it, and usually near a release. The first arrangement has many casual readers and no owner; the second has one owner and few readers. That is the practical reason the field-on-the-item arrangement stays closer to the truth: it is checked constantly by people who are not checking it. ## The practical answer: generate the spine, author the exceptions The arrangement that works in real teams is not a pure choice. 1. **Generate the spine.** Criterion, verifying cases, latest verdict, build under test, linked defects. All of it exists in the work already; querying it is cheaper than agreeing on it. 2. **Author only what the work cannot hold.** A rationale for accepting something partially verified, a note that a criterion is verified by an argument rather than a check. These have no field anywhere else. 3. **Mark authored columns as authored**, with the date and the person. A reader can then apply different trust to the derived spine, which is as fresh as the query, and to the authored margin, which is as fresh as its last edit. 4. **Snapshot at decision points.** If somebody will later need to know what was claimed on the day a version shipped, store the generated table as it stood, rather than keeping a hand-maintained document year-round to serve that one need. Two failure modes to name if asked. **Deriving from weak references** produces a clean-looking table full of nulls, and the temptation is then to fill them in by hand, which quietly converts the whole thing into an authored document with a machine's typography. **Authoring what could be derived** produces a table that disagrees with the work, and when the two disagree, people believe the table, which is the more expensive of the two mistakes.