Use Cases

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.

Project lead installs the extension: npm install @antora-tracer/core --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/core/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.

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., addresses:REQ-001[])

Team member includes rendering macros (tracer:links[], tracer:outgoing[], tracer: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 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.

Requirements Engineer resolves the use_case authoring guidance with antora-tracer role-guidance use_case to obtain the item template

Requirements Engineer determines the next available ID with antora-tracer next-id --prefix UC -i <path>

Requirements Engineer writes the use case item block ([#UC-NNN, item, role=use_case, …​]) following the Karl Wiegers template — actor, goal, preconditions, postconditions, main flow, and alternate flows

Requirements Engineer links the use case to the requirements it motivates with leads_to:REQ-NNN[] inline macros

Requirements Engineer includes tracer:links[] to render the relationship list

Requirements Engineer commits the file And triggers an Antora build

The extension registers the use case item And the leads_to relationships appear in the traceability matrix

The use_case role is not in the config: The extension registers the item with a warning. The use case is not part of the configured domain model until the role is added.

The role has no authoring guidance: The Requirements Engineer falls back to the generic Karl Wiegers template.

A precondition or postcondition is not testable: The use case is revised so both are measurable.

The Requirements Engineer links to a requirement that does not exist: The extension stores the relationship with a warning. The matrix shows a partial link.

Team member runs antora-tracer next-id --prefix <PREFIX> with a configured allocator

The CLI requests the next ID for the prefix from the shared allocator

The allocator atomically increments its counter for the prefix And returns a unique, zero-padded ID

Team member writes the item with the returned ID

Another team member on a different branch repeats the flow And receives the next, distinct ID

No allocator is configured: next-id falls back to a local max+1 scan, which cannot prevent duplicates under parallel work; the validate command detects any resulting collision at merge time.

The allocator is unreachable: next-id fails closed with an error And emits no ID.

An existing local sequence must continue: Team member seeds the allocator’s per-prefix start value with antora-tracer seed so it continues from the current maximum instead of colliding at 001.

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.

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 isolated, 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.

Requirements Engineer marks the successor as replacing the obsolete predecessor

Requirements Engineer runs the supersession check for the predecessor to list direct successors And incoming functional relationships requiring review

Requirements Engineer runs validation to confirm the supersession structure is valid — no self-reference, duplicate, or cycle — And to review stale functional-link warnings

The build renders the superseded item with a marker linking to every direct successor And current-state matrices omit the superseded item

Requirements Engineer reviews functional relationships that still target the obsolete item And updates them to the successor

When cleanup is due, Requirements Engineer archives the superseded item out of the active pages or removes an orphaned or isolated item after confirmation

Supersession structure is invalid (self-reference, duplicate, or cycle): Validation reports an error And the Requirements Engineer fixes the relationship.

A functional link still targets the superseded item: The link is retained And flagged as requiring review, naming every direct successor; validation warns without failing.

A dangling link of type supersedes or superseded_by: Reported as an advisory worklist item, not a validation error.

Hide superseded items from rendered output: The Requirements Engineer disables rendering of superseded items; the graph And matrices are unaffected.

Item is not superseded: The archive command refuses to move it.

Item is isolated (no relationships at all): Removal requires typing the item ID verbatim as a stronger confirmation.

Developer identifies the two source paths to compare — the base and the revision

Developer runs the diff command with both paths

The CLI prints the delta between the two graphs

Developer reviews items classified as added, removed, or modified by stable ID, with modified items naming the changed fields

Developer reviews relationship changes limited to items that survive in both snapshots

Developer uses the delta to plan the merge or document the change

An item was renamed without a supersedes relationship: The diff performs no rename detection — the old ID appears as removed And the new ID as added.

A superseded item: Its predecessor appears as removed And its successor as added, with the supersession relationship reported as a new relationship.

A relationship touches an item present in only one snapshot: The relationship delta is not reported.

The two snapshots are identical: An empty delta is printed And the command exits successfully.

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.

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 tracer:graph[] inside an item block to render a GraphViz diagram of that item’s direct relationships (colored by role, with labeled edges)

Architect embeds tracer: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 tracer:graph[ITEM-ID, 2] with a depth of 2: The graph shows two hops of relationships instead of one.

Architect places tracer: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.

Reader opens the site search on the published site

Reader enters a query matching the traceable item’s ID or title

The search returns matching results, including the traceable item

Reader selects the result that points to the item

The browser navigates directly to the item’s anchor on the page

The result points to a section heading rather than an item: The heading is indexed by the site’s existing section search, so the Reader lands on the heading instead.

No result matches the query: Reader refines the query or browses the navigation instead.