Requirements Traceability
Week 9 · Forward, backward, and what a change will touch
Week 9 · Forward, backward, and what a change will touch
The agent does not remember why it wrote the code. The matrix has to.
git blame says you wrote it. You do not remember. Neither does the agent: that was a different session.
Measured
With traceability: about 24% faster, and about 50% more correct solutions.
Skipped
In six open-source projects, about 40% of commits did not even name their issue.
When the cost of a discarded practice collapses, bring it back.
Mäder and Egyed, Empirical Software Engineering, 2015; Rath et al., ICSE 2018.
The agent
Does the upkeep.
A tool
Checks it: do the IDs resolve, does every row name a test?
You
Keep the meaning: what should trace to what.
An agent that judges its own links gives you confident, false assurance.
flowchart LR UC["Use case"] --> D["Design"] --> C["Code"] --> T["Test"]
Build
❌ Not started · 📐 Designed · 🟡 In progress · ✅ Built
Verify
✅ Verified · 🟡 Partial · 🔎 None
Built and tested are two facts. Keep them in two cells.
| Row | Design | Code | Tests | Build | Verify |
|---|---|---|---|---|---|
UC-NOT-remind-non-submitters |
design/not.md |
RemindNonSubmittersDialog.vue, ReminderController.sendReminders |
ReminderIntegrationTest, reminders.spec.cy.js |
✅ Built | ✅ Verified |
FR-NOT-weekly-reminder |
design/not.md |
WeeklyReminderScheduler |
WeeklyReminderSchedulerTest |
✅ Built | ✅ Verified |
An instructor starts one reminder; a timer starts the other. Two requirements, two rows.
Project Pulse, docs/traceability.md on main, cells trimmed.
Forward: is it built and tested?
Start at UC-EVA-submit-evaluation. Its row names SubmitTeamsEvaluations.vue, EvaluationService.addPeerEvaluation, and the tests. ✅ Built, ✅ Verified.
Backward: why does this code exist?
Start at WeeklyReminderScheduler. It traces to FR-NOT-weekly-reminder, a row of its own: no use case owns a timer.
ExportService.java appears in no row of your matrix. What could it be, and who decides?
A row reads ✅ Verified only when you can name a test that exercises the main flow and every extension, and it passes.
Verify: ✅ Verified. Tests: EvaluationServiceTest. The test: assertTrue(true).
| Shape | What you see | Repair |
|---|---|---|
| Specification right, code behind | A rule is written; the code does not enforce it | Conform the code |
| Code right, specification stale | The document describes behavior the system no longer has | Amend the document |
| Neither says anything | The code made a decision no document records | Decide it, then write it down |
FR-NOT-weekly-reminder, amended 2026-10-03
Remind only the students who still owe something (BR-submission-owed).
WeeklyReminderScheduler.sendWeeklyReminders
Kept emailing every student in the section, and its tests checked that it did.
For three weeks the row read 📐 Designed, not ✅ Built. The gap was traced, not hidden.
peerEvaluationAverage.setAverageTotalScore(
evaluations.stream().mapToDouble(PeerEvaluation::getTotalScore)
.average().orElse(0.0));A student nobody evaluated, and a student rated zero by everyone. What does the weekly report show for each?
The reminder
The rule and the code disagreed. A test written from the rule fails; a reviewer reading both sees it.
The 0.0 average
No rule exists. Nothing can fail, because only the code ever spoke.
Hand an agent an under-specified use case and it always picks something, in seconds, in code that looks exactly like a decision you made.
| UC | Build | Verify | Release |
|---|---|---|---|
UC-NOT-remind-non-submitters |
✅ Built | ✅ Verified | v1.6.0 |
UC-AI-critique |
❌ Not started | v1.8.0 |
|
UC-AI-draft-skeleton |
❌ Not started | Later |
v0.1.0 slice, v0.2.0 Checkpoint 3, v1.0.0 December, Spring, Out.Hours still needed = remaining v1.0.0 estimate midpoints × your ratio.
Forecast: 6 rows left in v1.0.0, 38 to 60 h at ratio 1.4; about 70 h available.Doesn't fit? Move rows out of v1.0.0 with your client at the next meeting. Change the scope, not the estimate.
Impact analysis: answer it before anyone edits code. The matrix turns it from a memory test into a lookup.
The client wants two weeks, not one, to finish a peer evaluation. What does that touch?
BR-evaluation-submission-window is the changed node. Start there.
UC-EVA-submit-evaluation
✅ Built. The row names the code and the tests that pin the window.
UC-NOT-remind-non-submitters
✅ Built since October 25. The change lands in code and tests.
Two weeks earlier it was a design edit. A change caught at design is cheap.
BR-active-weeks: "each active week is evaluated during the following calendar week".BR-evaluation-editable-until-close: editable while the window is open.The index records which requirements cite a rule, not which rules lean on each other. A search finds those.
Your list is the scope
Every ID and file from steps 1 and 2, in the issue.
The agent finds the reach
WeekKeys.previousWeek, shared by the window, the reminder, and the scheduled job, and getPreviousWeek() in the frontend's utils/week.
The IDs steer the agent before the change. The matrix checks what came back after it.
A file outside the list
Either an edge the matrix lacks (add it) or the agent wandered (send it back).
A file on the list, untouched
Needs a reason.
Two weeks means two weeks open at once. Which does the form open on? Which one is the reminder about?
Tell the agent "make it two weeks" and it answers all of these silently. That is the third drift shape, on purpose.
BR-evaluation-submission-window
Cited by 2 use cases. A small change.
BR-role-based-access
Cited by 41. A project-wide change.
"It's a one-line change." 41 use cases cite that line.
docs/traceability.md: list what the two-week change touches.docs/ for BR-evaluation-submission-window: what does it add?