How to Write Traceable Items

This guide covers the practical workflow for writing traceable items. For the complete syntax specification, see Item Macro Reference.

Write your first item

An item starts with the [item] block macro:

[#REQ-001, item, role=requirement, title="REQ-001 — User authentication"]
--
The system shall require authentication for all protected endpoints.
--

  • #REQ-001 — unique ID. Use a consistent prefix convention (see Choose ID conventions below)

  • role=requirement — must match a role in your configuration

  • title — display title. Defaults to the ID if omitted

  • -- delimiters — the block content goes between them

Add inline relationships

Inside the item block, add relationships using the <type>:TARGET-ID[] syntax:

[#DES-001, item, role=design]
--
JWT-based authentication service.

addresses:REQ-001[]           (1)
depends_on:DES-002[]          (2)
--
1 This design addresses the requirement REQ-001
2 This design depends on another design DES-002

Multiple targets in one type:

addresses:REQ-001,REQ-002,REQ-003[]

Inline relationship macros are invisible in rendered output — they are pure data markers for the traceability graph.

Choose ID conventions

While any unique string works, a consistent convention helps readability:

Pattern Example Convention

Role prefix

REQ-001, IMP-042, TEST-099

Two-to-four uppercase letters, hyphen, number

Hierarchical

SYS.SEC.AUTH-001

Dotted namespace

Domain prefix

PROJ-REQ-001

Project prefix

Use the next-id CLI command to get the next available ID without scanning the document manually:

npx antora-tracer next-id --prefix REQ -i docs/
# → REQ-004

The command auto-detects padding from existing IDs.

Add status and priority

Track the lifecycle of items with attributes:

[#REQ-001, item, role=requirement, title="REQ-001 — Auth", status="draft", priority="high"]
--
...
--

status and priority are free-form strings. They appear in the traceability graph and Neo4j export.

Display relationships in rendered output

Use the traceability:outgoing[] and traceability:incoming[] macros to show relationship lists:

[#DES-001, item, role=design]
--
JWT-based authentication.

addresses:REQ-001[]

     (1)
     (2)
--
1 Renders a list of items this item points to
2 Renders a list of items that point to this item

Enable these macros per page with the document attribute:

= My Page
:traceability-links: true
:traceability-style: table       (1)
:traceability-order: target-id   (2)
1 Display style: list (default), table, or inline
2 Sort order: target-id (default), target-title, or relation-type

See Traceability Macros Reference for all options.

Use partial files for items

You can define items in AsciiDoc partials and include them in pages:

// architecture.adoc
= Architecture
== Solution Strategy

The following items describe how individual quality goals are addressed by
architecture decisions documented in the xref:explanation/adr/index.adoc[ADRs] and quality
acceptance criteria in the xref:explanation/quality/index.adoc[Quality Attributes].

[#ARC-005, item, role=design, title="ARC-005 — Zero operational overhead"]
--
xref:explanation/quality/zero-operational-overhead.adoc[Zero operational overhead] is
achieved through an in-memory graph (xref:explanation/adr/0003-in-memory-graph.adoc[ADR-003])
no external services, and a minimal dependency tree
(xref:explanation/adr/0004-zero-framework.adoc[ADR-004]).
Optional features like Neo4j export degrade gracefully without warnings.



.Addresses
* xref:requirements:index.adoc#QA-055[QA-055 — Zero operational overhead]

--

[#ARC-006, item, role=design, title="ARC-006 — Configurable without code changes"]
--
xref:explanation/quality/configurable-without-code.adoc[Configurable without code changes]
is achieved through YAML-based roles, relations, and matrices via
`ConfigLoader`.
Built-in presets can be extended or overridden.
Items with unknown roles generate warnings, not errors — enabling
incremental domain model adoption.



.Addresses
* xref:requirements:index.adoc#QA-056[QA-056 — Configurable without code changes]

--

[#ARC-007, item, role=design, title="ARC-007 — Fail-fast with clear diagnostics"]
--
xref:explanation/quality/fail-fast-diagnostics.adoc[Fail-fast with clear diagnostics]
is achieved through role-based relation validation at processing time
and post-hoc re-validation for cross-file references.
Error messages
include file, line, item IDs with roles, and allowed alternatives.



.Addresses
* xref:requirements:index.adoc#QA-057[QA-057 — Fail-fast with clear diagnostics]

--

[#ARC-008, item, role=design, title="ARC-008 — No side effects on source files"]
--
xref:explanation/quality/no-side-effects.adoc[No side effects on source files]
is achieved by performing all content transformations on in-memory
buffers.
Source `.adoc` files are never written to.
Processing is idempotent.



.Addresses
* xref:requirements:index.adoc#QA-058[QA-058 — No side effects on source files]

--

[#ARC-009, item, role=design, title="ARC-009 — Testability by design"]
--
xref:explanation/quality/testability-by-design.adoc[Testability by design]
is achieved through constructor-based dependency injection
isolated test files per module, and graph state exposed for test access.
The regex-based parser (xref:explanation/adr/0002-regex-parser-over-ast.adoc[ADR-002])
is decoupled from Asciidoctor's API.



.Addresses
* xref:requirements:index.adoc#QA-059[QA-059 — Testability by design]


--

[#ARC-010, item, role=design, title="ARC-010 — Future-proofness"]
--
Future-proofness is achieved through ESM with `"type": "module"`
(xref:explanation/adr/0001-esm-over-cjs.adoc[ADR-001]), TypeScript strict mode
and a Node.js 20+ baseline (xref:explanation/adr/0005-typescript-strict-node20.adoc[ADR-005]).
The zero-framework policy avoids dependency on libraries with short upgrade cycles.



.Addresses
* xref:requirements:index.adoc#QA-061[QA-061 — Platform stability and longevity]

--

[#ARC-011, item, role=design, title="ARC-011 — Performance through indexing"]
--
Performance is achieved through forward, reverse, and inverse
relationship indexes (O(1) lookup), result caching with invalidation
on mutation, and BFS path finding with configurable `maxDepth`.



.Addresses
* xref:requirements:index.adoc#QA-062[QA-062 — Query and indexing performance]

--
// partials/04-solution-strategy.adoc
[#ARC-005, item, role=design]
== Solution Strategy
...

Partials are processed on equal footing with pages. Matrix links for partial items point to the source repository rather than rendered HTML (since partials don’t produce their own pages).

See How to use partial files with items for the full patterns and tradeoffs.

Share items across files

Items can live in any .adoc file in your Antora component. A requirement in one file can be referenced by an implementation in another — as long as the IDs match. The extension aggregates all items into a single graph.

Related