> ## 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. # Traceability Matrix > The Roboticks traceability matrix — requirement × test grid, filters, sorts, exports to CSV and ReqIF, heatmap colouring, drill-in to cells, saved views. # Traceability Matrix The matrix is the canonical UI for traceability. One row per requirement, one column per test, one cell per link. The colour of each row tells you the coverage state at a glance; clicking a cell drills into the test run that produced the result. ## Layout ``` tests → ┌──────────────────────────────────────────────┐ │ test_estop test_brake test_rth │ requirements REQ-014 │ ✅ pass — — │ confirmed REQ-015 │ — ❌ fail — │ regression REQ-027 │ — — ✅ pass │ confirmed REQ-101 │ — — — │ gap └──────────────────────────────────────────────┘ ``` The grid is rendered with TanStack Table — virtualised for projects with thousands of requirements, sticky headers, keyboard-navigable, and resizable columns. *\[Screenshot needed: matrix UI showing heatmap colouring, filter chips, and a hovered cell with run details]* ## Heatmap colour key | Colour | State | Meaning | | ------------ | ------------- | ------------------------------------------------ | | Green | `confirmed` | At least one confirming test passed on this SHA. | | Amber | `partial` | A confirming test passed and another failed. | | Red | `regression` | Was `confirmed` previously; now isn't. | | Grey | `unconfirmed` | Has a `@confirms` link but no run result. | | Outlined red | `gap` | No `@confirms` link to any test. | The legend at the top of the matrix is clickable — click `gap` to filter the view to only gap-state rows. ## Filters Filters compose. Stacking several narrows the view down to exactly what you need. | Filter | Examples | | ------------------- | ------------------------------------------------------------------------------ | | **State** | `confirmed`, `partial`, `regression`, `unconfirmed`, `gap`. | | **Type** | `safety`, `functional`, `performance`, `reliability`, `security`, `usability`. | | **ASIL / PL / SIL** | `ASIL-D`, `PLd`, `SIL-3` — and combinations. | | **Tag** | Any custom tag — `estop`, `latency-p99`, `battery`. | | **Standard** | A pinned standard — `ISO 10218-2:2025`, `IEC 61508`. | | **Repository** | For multi-repo projects, filter by source repo. | | **Source** | `reqif`, `pdf`, `manual`, `inline_yaml`, `llm`. | | **Priority** | `critical`, `high`, `medium`, `low`. | | **Text search** | Match against `title` and `text`. | Each filter renders as a chip at the top of the matrix. Click the X on a chip to remove it. ### Saved views Once you've composed a useful filter set, **Save view** persists it under a name (e.g. *"ASIL-D regressions"*). Saved views: * Are scoped to the project but visible to all members. * Get a direct URL you can paste in a Slack thread or PR comment. * Show in the sidebar of every team member's matrix view. A few teams use saved views as standing dashboards — *"Safety leads — open this every Monday morning"* — and link the URL in their team docs. ## Sorts Default sort is by requirement `id`. You can sort by: * `id` (lexicographic). * `priority` (`critical` first). * `asil_pl` (`ASIL-D` first). * `coverage_state` (`gap`, then `regression`, then `partial`, then `unconfirmed`, then `confirmed`). * `last_changed` (recency of any field edit). * `last_verified` (recency of last test run touching the requirement). Hold shift to compose sorts — *"first by ASIL descending, then by last verified ascending"* is a good triage view. ## Drill-in Click any cell to open the **Run detail drawer**: * The test source code at the SHA, with the `@confirms` line highlighted. * The JUnit row — assertion message, duration, retries. * Attached artifacts — MCAP bag, logs, screenshots. * The runner metadata — image tag, hardware, wall-clock. * The requirement detail with full text on the right. Click a row header (requirement) to open the **Requirement detail page** — the full text, history of edits, list of confirming tests, child requirements if any, and an audit trail. ## Tree vs flat mode Switch with the toggle in the toolbar. | | Flat | Tree | | ----------------- | ------------------------------------------ | ------------------------ | | Layout | One row per requirement, indented by depth | Collapsible groups | | Best for | Filtering, sorting, gap triage | Reviewing decomposition | | Rollup on parents | Yes, but as a separate row | Yes, on the group header | Both modes show identical data; the choice is purely visual. ## Graph view For visual reviewers, the **Graph view** renders the requirement → test graph as a force-directed diagram. Nodes are coloured by coverage state; edges are coloured by source (`@confirms`, manual, LLM-inferred). Graph view is best for: * Spotting clusters of `gap`-state requirements. * Reviewing the decomposition tree pre-audit. * Showing the matrix to non-engineering stakeholders. It's not a primary work surface — filter and sort on the table; explore on the graph. ## Exports Three formats, all from **Matrix → Export**: | Format | Contains | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **CSV** | One row per requirement-test link, with requirement fields, test path, last result, last run timestamp. | | **ReqIF** | Full requirement set with the `roboticks:verification` extension carrying coverage state. Re-importable into Polarion / Jama / codeBeamer / DOORS. See [ReqIF](/requirements/reqif). | | **PDF (matrix snapshot)** | A printable, paginated rendering of the current view (respecting filters). Useful for archive copies outside the evidence pack. | CSV is the most common — most regulated teams ingest it into their internal reporting before submission. ReqIF is for round-tripping back into the upstream requirements tool. ## Multi-repo behaviour For a project linked to multiple repos, the matrix gains a **Repository** column showing which repo a test lives in. Aggregation rules: * A requirement can be confirmed by tests in **any** repo in the project. * The Repository column is a filter target — drill the matrix to one repo for repo-scoped review. See [Multi-repo projects](/traceability/multi-repo) for the full model. ## Snapshot mode The toolbar has a snapshot picker. Default is **Live** (current state of the default branch). Switching to a snapshot — e.g. `v1.2.0` — shows the matrix as it existed at the moment the snapshot was cut. Cells are read-only in snapshot mode. This is the view auditors see. ## Performance The matrix is virtualised — rendering 10,000 requirements × 20,000 tests is a few hundred milliseconds. Saved views and filters apply server-side for projects above 1,000 requirements to keep the wire small. For projects above 100,000 requirements (large standards-derivation projects), open a ticket — we have an indexed query mode that needs to be flipped on per project. ## Next The state machine in detail. Filter to gap-only and close them. How the PR Check Run highlights affected requirements. Rollup across many repos in one project.