Item Macro Reference

Syntax

[#ID, item, role=<role>, title="ID — Title", status="draft", priority="high"]
--
Item content. Can span multiple paragraphs.

Inline relationships go anywhere inside the block:

<relation-type>:TARGET-ID[]
<relation-type>:TARGET-ID[]
--

Both -- (open block) and ==== (example block) are valid delimiters for the item block. -- renders the item inline with no frame; ==== renders it boxed with a shaded background. The choice is presentational — the parser treats them identically. This documentation uses --.

Attributes

Attribute Required Description

id

Yes

Unique identifier. Must be unique across all items in the graph. Recommended format: ROLE-NNN (e.g., REQ-001, STORY-042)

role

Yes

Must match a role defined in your configuration. Case-insensitive. Unknown roles generate a warning but the item is still stored

title

No

Display title. Defaults to the id if omitted. Used in matrix cells, macro output, and Neo4j export

status

No

Free-form status: draft, reviewed, approved, implemented, deprecated

priority

No

Free-form priority: high, medium, low

Any additional attributes are stored in the item’s attributes map and exported to Neo4j as node properties.

Inline Relationship Macros

A relationship is expressed as <relation-type>:TARGET-ID[] anywhere inside the item block:

[#DES-001, item, role=design]
--
Auth Service

addresses:REQ-001[]
depends_on:DES-002[]
--

Syntax rules

  • Multiple targets per type: addresses:REQ-001,REQ-002,REQ-003[]

  • Multiple types per item: write each on its own line

  • The TARGET-ID must match the id of another item in the graph

  • Missing targets generate a warning, not an error

Visibility

Inline relationship macros are always invisible in rendered output. They are pure data markers stored in the traceability graph. To display relationships in documentation, use:

  • traceability:outgoing[] — lists items this item points to

  • traceability:incoming[] — lists items that point to this item

  • traceability:links[] — shows both directions

See Traceability Macros Reference.

Validation

The extension validates items and relationships at processing time:

Role validation

  • Role exists: If role=widget and widget isn’t in the config, warning: Unknown role "widget". Known roles: requirement, design, test.

Relation validation

  • Relation allowed: Checks source role → target role against the relations map. Disallowed relations generate errors with the allowed types listed.

  • Target exists: Missing targets generate: Target item not found: MISSING-001.

Graph validation

  • Circular references: DFS-based cycle detection. Reports cycles with the full path: Circular reference detected: REQ-001 → REQ-002 → REQ-001.

  • Self-references: An item referencing itself is also detected and reported as circular.

Warnings don’t block processing; errors do. Unknown roles generate warnings (graceful degradation). Invalid relations generate errors.

Related