Use Cases

Team member identifies a concept that needs to be traceable — a requirement, a design decision, a test specification, or a dependency

Team member determines the next available ID for the item’s prefix using the CLI: antora-tracer next-id --prefix <PREFIX> -i <path>

Team member assigns the concept to a role defined in the project’s traceability domain model (requirement, design, test, etc.)

Team member writes the item using the [#ID, item, role=…​] block macro with a description between -- delimiters

Team member links the concept to related items already in the traceability graph using inline relationship macros (e.g., ``)

Team member includes rendering macros (traceability:links[], traceability:outgoing[], traceability:incoming[]) to display relationship lists in the rendered output

Team member commits the file And triggers an Antora build

The extension registers the item in the traceability graph And its relationships appear in the traceability matrix

No existing items share the prefix: The next-id command defaults to 3-digit padding and returns <PREFIX>-001.

Team member uses a role not in config: Extension registers the item with a warning. Processing continues.

Team member links to a target that does not exist: Extension stores the relationship with a warning. The matrix shows a partial link.

Team member writes an incomplete item block: The item may not register correctly in the traceability graph.

Team member includes rendering macros but no relationships exist: The placeholder is replaced with an empty section in the rendered output.

Requirements Engineer reviews the available built-in presets to identify the closest match

Requirements Engineer creates a traceability.yml file with extends: pointing to the chosen preset

Requirements Engineer adds roles not present in the preset (e.g., use_case, stakeholder)

Requirements Engineer defines relations for the new roles (e.g., use_case → requirement: [leads_to])

Requirements Engineer adds custom matrices for the new role combinations

Requirements Engineer runs the Antora build to verify the extended config is valid

The extension merges the user config with the preset And items using the new roles are accepted

Requirements Engineer extends a preset that does not exist: Extension reports an error listing available presets.

Requirements Engineer adds a role already in the preset: The duplicate is silently merged — the preset’s definition takes precedence.

Requirements Engineer defines a relation not allowed by the preset: The extension warns but does not block processing. Items using the relation may fail validation.

Requirements Engineer does not include extends: field: The config is treated as standalone — the preset is not loaded.

Requirements Engineer creates a .adoc file in the partials/ directory

Requirements Engineer moves related [item] blocks from a page into the partial file

Requirements Engineer replaces the moved items in the page with include::partial$…​[] directives

Requirements Engineer commits the changes And triggers an Antora build

The extension processes both the page and the partial — items from the partial are registered in the graph And matrix links point to the partial’s source location in the repository

Requirements Engineer includes a partial that defines no items: The partial is included normally in the page output but contributes nothing to the traceability graph.

Requirements Engineer includes a partial in multiple pages: The build fails with a duplicate-ID error naming both definitions.

Requirements Engineer references a partial item with xref:: Asciidoctor reports "target of xref not found" — partials do not produce HTML pages. Use inline relationship macros or link: URLs instead.

Reviewer opens the published Antora site in a browser

Reviewer navigates to the Traceability section in the navigation

Reviewer opens the relevant matrix (e.g., Requirements → Architecture, Requirements → Tests, Use Cases → Requirements)

Reviewer scans rows to identify items with missing coverage (red "missing" badge, 0.0%)

Reviewer clicks on cell items to navigate to the source page where the relationship is defined

Reviewer clicks on row items to navigate to the requirement’s definition

Reviewer notes gaps And either approves the coverage or requests additions

A matrix shows no items: The corresponding roles have no items defined. The matrix renders with zero rows.

A row shows partial coverage (yellow): Some but not all expected relationships exist. Reviewer investigates the specific gap.

Reviewer needs to see the source data in CSV: Reviewer can open the .csv variant of the matrix for offline analysis.

Reviewer needs coverage data for external tools: Reviewer can export the graph to Neo4j CSV or Cypher format for import into graph databases or compliance reports.

Project lead installs the extension: npm install antora-tracer --save-dev

Project lead reviews the built-in presets to find the closest match for the team’s domain (requirements-engineering, agile, medical-iec62304, minimal)

Project lead adds the extension to the Antora playbook with the chosen preset:

antora:
  extensions:
    - require: antora-tracer/antora-extension
      config:
        preset: requirements-engineering

Project lead creates a traceability.yml file extending the preset with any project-specific roles, relations, or matrices

Project lead adds :traceability-links: document attributes to the pages where relationship macros should render

Project lead adds matrix links to the site navigation (e.g., attachment$traceability/matrix-requirements-to-design.html)

Project lead runs a first Antora build to verify the extension initializes and matrices generate without errors

Project lead shares the setup with the team — team members can now write items in their AsciiDoc pages

The preset does not cover the team’s domain at all: Project lead uses preset init to bootstrap a custom preset from scratch and defines all roles, relations, and matrices manually.

The project does not have a partials/ directory yet: Project lead creates one. The extension processes partials automatically.

The first build shows zero items in matrices: Expected — the team has not written any items yet. Matrices render with empty rows and 0% coverage.

The team wants to adopt incrementally: Project lead configures the extension with minimal roles first. Additional roles, relations, and matrices are added later via config extension.

The project uses multiple Antora components: Project lead configures the extension in each component’s playbook or uses a shared config.

CI pipeline checks out the repository

CI pipeline runs antora-tracer process -i <pages-dir> --config traceability.yml to parse all items

CI pipeline runs antora-tracer validate -i <pages-dir> --config traceability.yml to check graph integrity

The validator reports errors (circular references, invalid relations) and warnings (unknown roles, missing targets)

If errors are found, the CI pipeline fails the build and the developer reviews the output

Developer fixes the issues — removes circular references, corrects relation types, or adds missing targets

Developer pushes the fix And CI re-runs validation

When validation passes (0 errors), the pipeline proceeds to build and deploy the Antora site

Validation finds only warnings (no errors): The build continues. Warnings are logged for review but do not block deployment.

Circular reference detected (e.g., A → B → A): The validator reports the full cycle path. Developer must break the cycle by removing one of the relationships.

Config file is missing or invalid: The validator exits with an error describing the config problem. Developer fixes traceability.yml.

No items found in the input directory: The validator reports 0 items. This may be intentional (new project) or indicate a path misconfiguration.

Developer wants to run validation locally before pushing: Same commands work outside CI — process then validate.

Data analyst runs antora-tracer export neo4j -i <pages-dir> --format csv to generate nodes.csv and relationships.csv

Data analyst imports the CSV files into Neo4j using LOAD CSV or the Neo4j Data Importer

Data analyst runs preset queries included with the config (e.g., "Uncovered Requirements," "Coverage Summary," "Traceability Chains")

Data analyst writes custom Cypher queries for project-specific questions

Data analyst shares findings — a coverage heatmap, a list of orphan items, or an impact analysis report

Data analyst prefers Cypher format: Uses --format cypher to generate an import.cypher file with CREATE statements instead of CSV.

Export contains items with special characters in titles: The exporter properly escapes commas, quotes, and newlines so CSV imports cleanly.

Data analyst wants to export only a subset: Runs export neo4j after a CI validation step that has already populated the graph with only the items of interest.

Neo4j is not available: The analyst can inspect the CSV files directly in a spreadsheet or use the Cypher file as documentation of the graph structure.

Architect adds :traceability-graph: true to a page’s document header

Architect embeds traceability:graph[] inside an item block to render a GraphViz diagram of that item’s direct relationships (colored by role, with labeled edges)

Architect embeds traceability:graph-coverage[] inside or outside item blocks to render Vega-Lite bar charts showing coverage

Architect builds the Antora site — macros are replaced with Kroki image URLs (SVG by default, PNG configurable)

Stakeholders view the page — the diagram shows the item’s dependency neighborhood and the bar chart shows coverage status

Stakeholders can click through from the diagram description to related items via xrefs

Architect uses traceability:graph[ITEM-ID, 2] with a depth of 2: The graph shows two hops of relationships instead of one.

Architect places traceability:graph-coverage[] outside an item block: The chart shows global coverage by role instead of per-item coverage.

The project builds PDFs: Architect sets krokiImageFormat: png in the playbook config — PNG images render correctly in PDF output where SVGs do not.

Kroki is unavailable or misconfigured: The macros render as fallback text with the item IDs, still providing value.

Developer identifies the ID of the item they intend to change or remove

Developer runs antora-tracer query reverse <ID> to list every item that references the target, with relationship type and source file and line

Developer runs antora-tracer query impact <ID> to list all items transitively connected to the target

Developer reviews the results to determine the full set of items affected by the change

Developer updates each referencing item — or confirms none exist — before making the change

Developer commits the change with all affected items accounted for

No item references the target: reverse returns an empty result and exits 0. The change is safe from a traceability perspective.

The target ID does not exist: The command exits 1 with an "Item not found" warning. Developer verifies the ID spelling or confirms the item was already removed.

Developer needs machine-readable output: Developer adds --json for structured output consumable by scripts or AI coding agents.

Developer needs the chain between two specific items: Developer runs query path <from> <to>. The shortest relationship path prints, or the command exits 1 with "No path found".

Developer wants to find items with no relationships: Developer runs query orphaned, optionally filtered with --role.

Developer wants to limit the search: Developer passes -i <path> to scan a specific directory or file instead of the current directory.