Roles Reference

Every traceability item is a role with an ID prefix, a set of fields, and a state machine. This page is the authoritative reference for authoring items.

Roles and prefixes

Role Prefix Initial status Purpose

change

CHG

proposed

The entry point: rationale, outcome, and scope of one change.

requirement

REQ

draft

The spec unit: an observable obligation a change addresses.

decision

DEC

proposed

A durable record of a domain or specification choice.

test

TST

—

Verification evidence carrying verifies:REQ-NNN[].

Growth roles (use_case, design_concept, goal, scenario, arc42) are available when declared in traceability.yml.

Requirements

A requirement states what the system must do — never how.

Use EARS patterns:

  • Ubiquitous: The system SHALL <behaviour>.

  • Event-driven: WHEN <trigger>, the system SHALL <behaviour>.

  • State-driven: WHILE <state>, the system SHALL <behaviour>.

  • Unwanted behaviour: IF <condition>, THEN the system SHALL <behaviour>.

Scenarios stay as prose inside the requirement body.

[#REQ-001, item, role=requirement, status=draft, title="Short title"]
--
The system SHALL <observable behaviour>.

WHEN <condition>, the system SHALL <behaviour>.

tracer:links[]
--

Changes

A change is the entry point. Its body carries Rationale::, Outcome::, and Out-of-scope:: labeled-list fields, then typed relation macros.

[#CHG-001, item, role=change, status=proposed, title="Change title"]
--
Rationale:: Why this change is needed.
Outcome:: What the change produces.
Out-of-scope:: What the change excludes.

addresses:REQ-NNN[]
records:DEC-NNN[]

tracer:links[]
--

Decisions

A decision preserves a domain or specification choice.

[#DEC-001, item, role=decision, status=proposed, title="Decision title"]
--
Context:: Why is this decision needed?
Decision:: What was decided?
Consequences:: What follows?

tracer:links[]
--

Decisions may additionally carry Options:: (per-option pros and cons) and Rationale:: fields, following the MADR shape documented in the decision guidance.

Relation macros

A relation macro <relation>:<ID>[] is written in the source item. The reverse name is derived for queries.

Source → Target

Macro

Reverse

Used in

change → requirement

addresses:REQ-NNN[]

addressed_by

change

change → decision

records:DEC-NNN[]

recorded_by

change

requirement → requirement

supersedes:REQ-OLD[]

superseded_by

requirement

test → requirement

verifies:REQ-NNN[]

verified_by

test

Workflow states

Use the status attribute to mark progression.

Role

States

requirement

draft → reviewed → approved → superseded · withdrawn

change

proposed → refined → accepted → implemented → verified → closed · rejected

decision

proposed → accepted → rejected · superseded

The accepted gate is enforced by validation: an accepted change must address at least one requirement. Other transitions are declarative and reviewed via Git.