> ## 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 Overview
> What traceability means in Roboticks — the coverage state machine, where links come from, and how the SDK's @confirms decorator feeds the engine.
# Traceability Overview
Traceability in Roboticks is the live mapping from requirements to tests to results. Every requirement has a coverage state. Every state is computed from concrete artifacts — a `@confirms` decorator in source, a JUnit row, a pass/fail flag — not from a hand-curated spreadsheet that drifts the moment someone is on holiday.
**Traceability is the diagonal of the V-model.** Requirements engineering owns the left arm; verification engineering owns the right arm; Roboticks owns the link between them. Without that link, the V-model is two disconnected staircases.
## The five coverage states
Each requirement is in exactly one of these states per SHA:
| State | Meaning |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `confirmed` | At least one test annotated `@confirms("REQ-...")` passed on this SHA. |
| `partial` | A confirming test passed **and** at least one other confirming test failed. The requirement is partially verified — likely flakiness or an incomplete behavioural cover. |
| `regression` | The requirement was `confirmed` on a prior SHA on this branch but now isn't. The strongest signal we emit. |
| `unconfirmed` | A `@confirms` link exists but no run has produced a result yet. Common right after a test is written but before it has run on the platform. |
| `gap` | No test annotates this requirement at all. The most actionable state — see [Gap analysis](/traceability/gaps). |
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
stateDiagram-v2
[*] --> gap: Requirement created
gap --> unconfirmed: @confirms link added
unconfirmed --> confirmed: Test passes
unconfirmed --> partial: Some pass, some fail
confirmed --> regression: Was confirmed, now fails
regression --> confirmed: Fix lands, test passes
confirmed --> partial: Additional failing test added
partial --> confirmed: All confirming tests pass
```
Hierarchy rolls these states up — see [Coverage](/traceability/coverage) for the per-state semantics on parent requirements.
## Where links come from
Three sources, all merged into a single `RequirementLink` table on the backend:
### 1. The `@confirms` decorator (primary)
The SDK exports a decorator. You annotate a test with it. The pytest plugin (or the equivalent for gtest / launch\_testing) emits the link into JUnit metadata. The backend reads it on ingest.
```python theme={null}
from roboticks import confirms, deadline
@confirms("REQ-014")
@deadline(milliseconds=100)
def test_estop_halts_motion(robot):
...
```
For C++/gtest:
```cpp theme={null}
#include
TEST(EStop, HaltsWithin100ms) {
ROBOTICKS_CONFIRMS("REQ-014");
// ...
}
```
Both render the same `` in JUnit XML. The backend parses these into `RequirementLink` rows.
### 2. Manual links in the dashboard
Right-click a cell in the [matrix](/traceability/matrix) and pick **Link**. Useful for tests in third-party suites you can't annotate, or for `verification_method: inspection` requirements that get human sign-off rather than a passing test.
Manually-created links are flagged in the audit trail with the user who added them; they're not silently equivalent to source-code-derived links.
### 3. LLM-suggested links (low-confidence, optional)
For mature repos with a lot of legacy tests, Roboticks can suggest links by matching test names and docstrings against requirement text via Bedrock Claude. Every suggested link is flagged `source: llm` and **requires human acceptance** before it counts toward coverage. See [Change-impact analysis](/traceability/change-impact) for how LLM-inferred links surface on PRs.
## What you see on each surface
| Surface | What it shows |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [**Check Run**](/github-app/check-runs) | Affected requirements on this PR, before/after coverage, regressions called out. |
| [**Matrix**](/traceability/matrix) | Full requirement × test grid, filterable / sortable, with heatmap colouring per coverage state. |
| [**Gap dashboard**](/traceability/gaps) | The list of `gap`-state requirements. The list you work down on a quiet Friday afternoon. |
| [**Graph view**](/traceability/matrix#graph-view) | Visual mode — useful when reviewing decomposition for an upcoming audit. |
| [**Evidence pack**](/evidence/generation) | Snapshot of the full matrix per release, signed in the hash chain. |
## How traceability runs on a PR
```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
sequenceDiagram
participant Dev
participant GH as GitHub
participant Plat as Roboticks
participant Run as Runner
Dev->>GH: git push
GH->>Plat: pull_request webhook
Plat->>Run: dispatch test job
Run->>Run: pytest with roboticks plugin
Run->>Plat: JUnit + @confirms metadata
Plat->>Plat: 1. Parse links
2. Update coverage states
3. Diff vs base SHA
Plat->>GH: Check Run (coverage delta)
Plat->>Plat: Persist snapshot if release SHA
```
The expensive piece — the actual test run — happens on a runner ([hosted or self-hosted](/runners/overview)). Roboticks itself is the orchestrator and the merge point of every signal.
## What traceability is not
* **Not a static analysis.** A test that compiles but never runs doesn't move a requirement out of `gap` — only a run does.
* **Not a coverage percentage in lines of code.** This is requirement coverage, not source-line coverage. Two systems with the same line-coverage can have wildly different requirement-coverage.
* **Not a substitute for review.** A test that passes proves what the test asserts; whether what the test asserts is what the requirement actually means is a judgement call — that's why every link is recorded with author and timestamp.
## A worked example
You have one requirement and one test:
```yaml theme={null}
- id: REQ-014
title: E-stop halts motion within 100 ms
type: safety
asil_pl: PLd
text: |
On assertion of E-stop, all actuators reach safe stop within 100 ms.
```
```python theme={null}
@confirms("REQ-014")
@deadline(milliseconds=100)
def test_estop(robot):
robot.command_velocity(1.0)
robot.assert_estop()
robot.wait_until_stopped()
```
Then:
1. You push the YAML alone — `REQ-014` is `gap` (no test).
2. You push the test alone (no `@confirms`) — `REQ-014` is still `gap`.
3. You push the test with `@confirms("REQ-014")` but it hasn't run yet — `REQ-014` is `unconfirmed`.
4. The PR-time run passes — `REQ-014` is `confirmed`.
5. Someone changes the brake code, the test now takes 215 ms — `REQ-014` is `regression`.
That's the whole loop. Everything else in this section is detail on top of it.
## Next
The requirement × test grid with filters and exports.
State machine details, multi-repo rollup, snapshot vs live.
The list of unconfirmed requirements and AI-suggested skeletons.
How a code diff maps to affected requirements on a PR.