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.

​
Uploading Requirements

Four ways in. Pick the one that matches where your requirements live today.
PathBest forRound-tripHuman-in-loop
ReqIFPolarion / Jama / codeBeamer / DOORS usersYes, lossless on the supported subsetNo
PDFStandards text (ISO 10218), legacy SRS docs, scanned specsOne-way (PDF → Roboticks)Yes — review before commit
Inline YAMLSmall projects, code-adjacent specsYes, the file is the source of truthNo
ManualAd-hoc additions, sandbox experimentsN/ANo

​
ReqIF

ReqIF (Requirements Interchange Format) is the OMG-standardised XML format every serious requirements tool exports. Roboticks ingests a subset that covers ~95% of real-world payloads and re-exports without losing the fields we ingest.
1

Export from your tool

Document → Export → ReqIF. Pick the work item types you want (typically Requirement, Safety Requirement).
2

Upload to Roboticks

Dashboard → Requirements → Upload → ReqIF. Drag in the .reqif or .reqifz (zipped) file. Files up to 100 MB upload directly; larger payloads use a pre-signed S3 URL automatically.
3

Map work item types

Roboticks shows the work item types it found in the ReqIF and asks which map to safety, functional, performance, etc. The mapping is remembered per project — subsequent uploads from the same tool skip this step.[Screenshot needed: work-item-type mapping table]
4

Confirm and commit

Review the parsed count by type and click Ingest. Validation runs in the background; you get a notification when the import is complete, typically within seconds.
See ReqIF round-trip for the field mapping table and re-export.

​
PDF

For standards text and legacy documents, Roboticks runs the PDF through a Bedrock Claude extraction pipeline that returns structured requirements. Every extracted requirement is human-reviewed before it lands in your project — we don’t silently commit LLM output.
1

Upload the PDF

Dashboard → Requirements → Upload → PDF. Drop in the file. Encrypted PDFs need to be unlocked first.
2

Extraction runs

Roboticks chunks the PDF, runs each section through Claude with a tightly-scoped extraction prompt, and returns candidate requirements with a confidence score per field.Progress appears in the dashboard. A 200-page ISO standard typically takes 60–120 seconds.
3

Review

Each candidate is shown with the source PDF excerpt side-by-side. Fields with low confidence (e.g. an ambiguous ASIL classification) are flagged amber. You can:
  • Accept as-is.
  • Edit then accept.
  • Reject — the candidate is dropped.
  • Bulk accept a confidence band (e.g. “accept all with confidence ≥ 0.85”).
[Screenshot needed: PDF review pane with source excerpt and candidate fields]
4

Commit

Accepted candidates are ingested as source: pdf with source_doc_id pointing back to the upload. The PDF itself is retained — the audit trail shows the exact source excerpt for every requirement.
LLM extraction is assistive, not authoritative. We surface it as candidates because regulators expect a human in the loop on requirement derivation. Roboticks will refuse to commit unreviewed candidates into a snapshot.

​
Inline YAML

The simplest path — a YAML file in your repo. Best when the spec lives close to the code and the team is comfortable with PR review for spec changes.

​
File location

your-repo/
├── roboticks/
│   └── requirements.yaml
├── src/
└── tests/
The file lives at the repo root under roboticks/. The GitHub App reads it on every push to the default branch.

​
Minimal example

- id: REQ-001
  title: E-stop halts motion within 100 ms
  type: safety
  asil_pl: PLd
  text: |
    On assertion of the E-stop input, all actuators must reach
    a safe stop state within 100 ms, measured at the wheel encoders.

- id: REQ-002
  title: Battery low triggers return-to-home
  type: functional
  text: |
    When battery state of charge drops below 20%, the AMR shall
    abort the current task and navigate to the configured home dock.
Push to the default branch. The GitHub App ingests the file; you’ll see the requirements appear in the dashboard within a few seconds. Full schema, hierarchy, and verification fields are in Authoring.

​
Manual

For one-off additions:
1

Open Requirements

Dashboard → Requirements → New Requirement.
2

Fill the form

Required: external_id, title, text, type. Optional: asil_pl, parent_id, tags, verification_method.
3

Save

The requirement is created with source: manual. It behaves identically to other requirements — links, snapshots, audit trail.
Manual entry is convenient but doesn’t scale. If you find yourself adding more than a handful, move them to inline YAML so they live in source control.

​
Conflict handling

If an upload contains an external_id that already exists in the project:
  • ReqIF / inline YAML — the existing requirement is updated in place. Edits are recorded in the audit trail. If the requirement is part of a snapshotted release, a new version is created (the old version stays linked to the prior release).
  • PDF — the candidate is flagged in review with the existing requirement so you can pick update, replace, or create as new.
  • Manual — the form rejects on duplicate external_id.

​
Validation

Every upload path runs the same validation:
  1. JSON Schema check against requirement.schema.json.
  2. parent_id resolution — if a referenced parent doesn’t exist, the upload is rejected with a list of missing IDs.
  3. Cycle detection on the hierarchy — circular parent chains are rejected.
  4. external_id uniqueness within the project.
Failures land in Requirements → Upload history with the offending row and the validation message.

​
Next

ReqIF round-trip

Field mappings and re-export.

Authoring YAML

Schema, types, ASIL annotations.

Hierarchy

Parent / child rollup rules.

Snapshotting

What freezes at release time.