Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Requirement Hierarchy

Real systems have requirements that decompose. “The AMR shall operate safely in shared spaces” is the system-level statement; underneath it sit a dozen subsystem requirements, and underneath each of those, the testable component statements. Roboticks models this as a tree via the parent_id field, and rolls coverage up the tree automatically.

​
The tree

Each requirement points at its parent with parent_id. The root nodes have parent_id unset. A requirement can have any number of children; it has at most one parent.

​
Declaring hierarchy in inline YAML

- id: SYS-001
  title: AMR operates safely in shared spaces
  type: safety
  text: ...

- id: SUB-010
  title: Safety subsystem
  type: safety
  parent_id: SYS-001
  text: ...

- id: REQ-014
  title: E-stop halts motion within 100 ms
  type: safety
  parent_id: SUB-010
  asil_pl: PLd
  text: ...
Order in the file doesn’t matter — parents and children can appear in any order. Roboticks resolves references after the full file is parsed.

​
Declaring hierarchy in ReqIF

ReqIF imports use the <SPEC-HIERARCHY> element. Polarion, Jama, codeBeamer, and DOORS all emit it; Roboticks reads it directly without any extra mapping. See ReqIF for the field tables.

​
Constraints

RuleWhy
A parent must exist in the same projectWe won’t link across projects; copy or factor first.
No cyclesThe hierarchy is a tree, not a graph. A cycle is a modelling error and is rejected on import.
At most one parent per requirementMulti-parent makes rollup ambiguous. If a requirement satisfies two parents, the second relationship is an inter-requirement link, not a parent (see ReqIF link semantics).
Children inherit type from the parent only if unsetThe default is conservative — children stay functional unless explicitly marked safety.

​
Coverage rollup

The coverage state of a parent is computed from its descendants:
All descendants are…Parent is…
confirmed (or have only verification methods other than test)confirmed
At least one gapgap
At least one regressionregression
Mixed confirmed + unconfirmed, no failurespartial
Any failingpartial
In short: a parent is only as healthy as its weakest descendant. This is what the auditor expects — “the safety subsystem is verified” must mean every requirement inside the safety subsystem is verified, not just three of five. In the example above, SUB-010 rolls up to partial because REQ-015 has no confirming test. Once a confirming test is added, SUB-010 becomes confirmed.

​
Verification methods other than test

Real audits accept four verification methods — test, inspection, analysis, demonstration. Roboticks confirms test; the others are recorded for the audit trail and excluded from the rollup denominator. So if a leaf requirement has verification_method: inspection, its parent’s rollup ignores it. This is the auditor-friendly behaviour: don’t penalise the test-coverage signal for requirements that were never going to be test-verified.

​
The matrix view

The traceability matrix (see Matrix) supports two display modes:
  • Flat — one row per requirement, indented by depth. Best for filtering and sorting.
  • Tree — collapsible groups. Best for exploring decomposition.
Both modes show the rolled-up state on parent rows. A parent showing partial is a hint to expand and find the weak descendant.

​
Walking the tree from the SDK

from roboticks import Client

client = Client()
req = client.requirements.get("SYS-001")

for descendant in req.descendants():
    print(descendant.id, descendant.coverage_state)
descendants() is a generator that walks the tree breadth-first. Use it in custom dashboards or release scripts that need to assert “every descendant of SYS-001 is confirmed before we ship”.

​
Aggregated coverage across projects

A single Roboticks project can host multiple top-level (root) requirements — e.g. one root per subsystem owned by a different team. The rollup is computed per root. The dashboard summary shows the count of confirmed / partial / gap per root, plus an aggregated percentage across all roots. For multi-project rollups (across organisational scope), use the org-level Compliance dashboard — see Compliance overview.

​
Editing the tree

Three kinds of edit:
  1. Add a child — appears under the parent immediately. Rollup recomputes on the next coverage update.
  2. Change a parent_id — the requirement moves in the tree. Both the old and new parents get a rollup recomputation. The audit trail records both ends of the move.
  3. Delete a node with children — rejected. Re-parent the children first, then delete. This prevents accidental orphan-trees.
Edits after a snapshot follow the snapshotting rules: the snapshot keeps the old tree shape; the live tree evolves.

​
Next

Snapshotting

What the tree looks like at release time.

Coverage

The state machine in detail.

Matrix

Flat vs tree display modes.

Multi-repo projects

Rollup across many repos in one project.