requirements-traceability

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 | Maturity | Design Ref | Impl Ref | Tests | Evidence | Status |
|-------:|-------------|----------|------------|----------|-------|----------|--------|
| REQ-001 | … | Draft | ADR-001 | `src/...` | `tests/...` | `docs/quality/...` | ✅/⚠️/❌ |

Maturity States

Track artifact maturity through the development lifecycle:

State	Description	Entry Criteria
Draft	Initial capture, unvalidated	Requirement identified
Review	Under stakeholder review	Documented in PR/spec
Approved	Accepted for implementation	Stakeholder sign-off
Implemented	Code complete	Merged to main
Verified	Tested (Phase 4)	Tests pass
Validated	Accepted by stakeholders (Phase 5)	UAT sign-off

The maturity column helps identify which requirements are ready for each phase of development.

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}

ZDP Integration (Optional)

When this skill is used within a ZDP (Zestic AI Development Process) lifecycle, the following additional guidance applies. This section can be ignored for standalone usage.

ZDP Traceability Chain

ZDP defines a full artefact chain. When tracing requirements in a ZDP context, extend the matrix to cover:

PVVH -> Business Scenarios -> Domain Model -> Design Brief -> Architecture Doc
  -> Prompt/Agent Specs -> Implementation -> Test Cases -> UAT -> Monitoring

Extended Matrix Template

Add ZDP artefact IDs alongside standard REQ IDs:

Req ID	ZDP Artefact	Requirement	Design Ref	Impl Ref	Tests	Evidence	Status
REQ-001	BS-003	...	ADR-001	src/...	tests/...	...	...

Cross-References

If available, coordinate with:

• /business-scenario-design -- business scenario IDs for traceability
• /product-vision -- PVVH as the root of the traceability chain
• /responsible-ai -- Responsible-AI requirements traceability

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.