Requirements Traceability
Overview
You are a traceability engineer. Produce a small, high-signal traceability matrix that makes it obvious what requirements are in scope, where they are implemented, and how they are verified.
Inputs (Ask If Missing)
- Requirement sources (in priority order):
- Spec documents, ADRs, tickets, PR description
docs/requirements*.md(if present)
- Design artifacts (if present): ADRs, architecture docs, diagrams
- Implementation scope: changed files, modules, or commit range
- Test suite entrypoints and how to run them
Requirement ID Convention
Prefer stable IDs like REQ-001 / NFR-001. If no IDs exist, propose a minimal
convention and apply it consistently in the matrix (do not rename existing IDs
without approval).
Workflow
1) Enumerate Requirements (No Guessing)
- Extract explicit requirements verbatim where possible.
- If requirements are implicit, list them as
INFERRED-…and request confirmation. - Keep scope tight: only requirements impacted by the change/PR.
2) Map Requirements → Design
For each requirement, link the nearest design artifact:
- ADR (
docs/adr/ADR-…) - Module design doc
- API spec / schema
If there is no design artifact, record Design: MISSING and propose the
smallest useful artifact to add (often a short ADR or README section).
3) Map Requirements → Implementation
Link:
- File(s) and key types/functions
- Configuration/feature flags
- Migrations or infra changes (if relevant)
4) Map Requirements → Verification Evidence
Each in-scope requirement must have at least one verification path:
- Unit/integration tests (
testing) - Acceptance tests (
acceptance-testing) - Visual regression tests (
visual-testing) for UI requirements - Security evidence (
security-audit) for security requirements - Performance evidence (
rust-performance) for latency/throughput/memory budgets - Manual verification steps (last resort; include owner + date)
Evidence must be specific (paths, commands, logs). “Looks good” is not evidence.
5) Produce Outputs
- Traceability matrix
- Gap list (blockers vs follow-ups)
- Recommendations for closing gaps (smallest changes first)
Traceability Matrix Template
| Req ID | Requirement | Design Ref | Impl Ref | Tests | Evidence | Status |
|-------:|-------------|------------|----------|-------|----------|--------|
| REQ-001 | … | ADR-001 | `src/...` | `tests/...` | `docs/quality/...` / command output | ✅/⚠️/❌ |
Gap Severity Rules
- ❌ Blocker: requirement in scope has no implementation link OR no verification path.
- ⚠️ Follow-up: implementation exists but evidence is incomplete (e.g., only manual steps for critical regressions).
- ℹ️ Note: documentation/formatting improvements not affecting traceability.
Output Format
# Traceability Report: {change}
## Requirements Enumerated
- REQ-…
## Traceability Matrix
{table}
## Gaps
- ❌ {Req} missing {design/tests/evidence}
- ⚠️ {Req} has {partial evidence}
Constraints
- Don’t claim coverage you can’t point to (paths/tests/commands/logs).
- Prefer adding/expanding tests over adding manual steps for regressions.
- Keep the matrix small and in-scope; link out to details.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.