> ## 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. # Requirements Overview > What a Requirement is in Roboticks, the four ingestion paths (ReqIF, PDF, inline YAML, manual), the hierarchy model, and the per-release snapshotting policy. # Requirements Overview A **Requirement** in Roboticks is a single, addressable, testable statement of intent — *"E-stop halts motion within 100 ms"*, *"battery low triggers return-to-home"*, *"perception latency stays under 50 ms at p99"*. Each one has an ID. Each one can be linked to one or more tests. Each one carries its own audit trail. Requirements are **the unit of truth** in Roboticks. Test results, evidence packs, and Check Run summaries are all measured against the requirement set in scope for the run. ## Anatomy of a Requirement | Field | Type | Notes | | --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Roboticks-assigned. Stable across renames. | | `external_id` | string | The ID in your upstream system — e.g. `REQ-014`, `JIRA-RT-227`, `Polarion:RT-1003`. | | `title` | string | A one-line headline. Shown in matrix rows and Check Run summaries. | | `text` | markdown | The full requirement text. | | `type` | enum | `functional` · `safety` · `performance` · `reliability` · `security` · `usability`. | | `asil_pl` | string \| null | Safety integrity level. ASIL-A/B/C/D (ISO 26262), PLa..e (ISO 13849), SIL-1..4 (IEC 61508). | | `source` | enum | `reqif` · `pdf` · `manual` · `llm` · `inline_yaml`. | | `source_doc_id` | string \| null | Pointer back to the originating document (ReqIF file, PDF, etc.). | | `parent_id` | string \| null | Used to build hierarchies — system → subsystem → component. See [Hierarchy](/requirements/hierarchy). | | `tags` | string\[] | Free-form labels. Drive filters in the matrix. | | `verification_method` | enum | `test` · `inspection` · `analysis` · `demonstration`. Roboticks confirms `test`; the others are tracked for the audit trail but verified out of band. | The canonical JSON Schema lives at [`roboticks-sdk/schemas/requirement.schema.json`](https://github.com/roboticks-io/roboticks-sdk/blob/main/schemas/requirement.schema.json) — every ingest path validates against it. ## The four ingestion paths You can mix and match per project — for example, ingest a ReqIF export from Jama for the production set and use inline YAML for sandbox/exploratory work. The industry standard XML format. Round-trippable — export from Polarion, Jama, codeBeamer, or DOORS and re-export later without losing fields. Bedrock Claude extracts structured requirements from a PDF (ISO 10218 text, internal SRS) into the schema. Low-confidence extractions are flagged for human review before commit. Commit `roboticks/requirements.yaml` to your repo. Simplest for small projects; lives next to the tests and ships through the same PR review. Add requirements one at a time in the dashboard. Best for ad-hoc additions or quick spikes. ## Hierarchy Requirements form a tree via `parent_id`. A common shape: ```mermaid theme={null} %%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%% flowchart TD SYS["SYS-001
AMR shall move safely"] --> SUB1["SUB-010
Safety subsystem"] SYS --> SUB2["SUB-020
Motion subsystem"] SUB1 --> COMP1["REQ-014
E-stop halts motion in 100 ms"] SUB1 --> COMP2["REQ-015
Brake releases on reset"] SUB2 --> COMP3["REQ-022
Max velocity 1.5 m/s"] ``` Coverage rolls up: a parent requirement is `confirmed` if **all** child requirements are confirmed. See [Hierarchy](/requirements/hierarchy) for the full rollup rules. ## Snapshotting When you cut a release, Roboticks freezes the requirement set into an **immutable snapshot**. From that point on: * Editing a snapshotted requirement creates a **new version**. The release continues to reference the version that was in scope at snapshot time. * The evidence pack generated for the release embeds the snapshot. Anyone — auditor, future self, regulator — can replay exactly what the release was verified against. * The audit trail records every edit, with author, timestamp, and diff. This is what makes Roboticks audit-grade: a release passes or fails against the requirement set that existed at the moment it was cut, not whatever the live state happens to be when the auditor opens the package three years later. Full details in [Snapshotting](/requirements/snapshotting). ## Lifecycle of a requirement ```mermaid theme={null} %%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%% flowchart LR A["Ingested
(ReqIF / PDF / inline / manual)"] --> B["Linked
(@confirms decorator on tests)"] B --> C["Verified
(tests pass on a SHA)"] C --> D["Snapshotted
(release cut)"] D --> E["Archived
(evidence pack, 10 yr Glacier)"] ``` Each stage adds an entry to the requirement's audit trail. The trail is exposed in the dashboard under the requirement detail page and exported in full in the evidence pack. ## Where requirements appear in the platform | Surface | What you see | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | [**Traceability matrix**](/traceability/matrix) | One row per requirement, one column per test, coloured by coverage state. | | [**Check Run summary**](/github-app/check-runs) | Affected requirements on this PR, with before/after coverage. | | [**Evidence pack**](/evidence/generation) | The snapshotted requirement set with verification status, signed in the hash chain. | | [**Standards updates**](/standards/overview) | When a pinned standard's amendment touches a requirement, the requirement is flagged with the impacted clause. | ## What requirements are not * **Not user stories.** A user story is "as a forklift operator, I want to pick a pallet"; a requirement is "the perception stack shall detect a EUR-pallet at 5 m with 99% recall". User stories live in Jira/Linear; requirements live here. * **Not test cases.** A test confirms a requirement; the requirement is the spec. * **Not free-text design notes.** Anything you can't bind a pass/fail criterion to belongs in your design doc, not in Roboticks. ## Next Step-by-step for each of the four ingestion paths. The schema, with examples per requirement type. Polarion / Jama / codeBeamer / DOORS field mappings. Per-release immutability and the audit trail.