> ## 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

> Step-by-step upload flow for ReqIF, PDF, inline YAML, and manual entry. Examples and validation rules for each path.

# Uploading Requirements

Four ways in. Pick the one that matches where your requirements live today.

| Path                        | Best for                                                   | Round-trip                             | Human-in-loop              |
| --------------------------- | ---------------------------------------------------------- | -------------------------------------- | -------------------------- |
| [ReqIF](#reqif)             | Polarion / Jama / codeBeamer / DOORS users                 | Yes, lossless on the supported subset  | No                         |
| [PDF](#pdf)                 | Standards text (ISO 10218), legacy SRS docs, scanned specs | One-way (PDF → Roboticks)              | Yes — review before commit |
| [Inline YAML](#inline-yaml) | Small projects, code-adjacent specs                        | Yes, the file *is* the source of truth | No                         |
| [Manual](#manual)           | Ad-hoc additions, sandbox experiments                      | N/A                                    | No                         |

## 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.

<Steps>
  <Step title="Export from your tool">
    <Tabs>
      <Tab title="Polarion">
        Document → **Export → ReqIF**. Pick the work item types you want (typically `Requirement`, `Safety Requirement`).
      </Tab>

      <Tab title="Jama">
        Project → **Export → ReqIF**. Include the item types and the trace links between them.
      </Tab>

      <Tab title="codeBeamer">
        Tracker → **Export → ReqIF/CSV → ReqIF**. Include parent/child relations.
      </Tab>

      <Tab title="DOORS">
        Module → **File → Export → ReqIF**. Include child modules if you want the full system → component tree.
      </Tab>
    </Tabs>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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]*
  </Step>

  <Step title="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.
  </Step>
</Steps>

See [ReqIF round-trip](/requirements/reqif) 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.

<Steps>
  <Step title="Upload the PDF">
    Dashboard → **Requirements → Upload → PDF**. Drop in the file. Encrypted PDFs need to be unlocked first.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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]*
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## 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

```yaml theme={null}
- 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](/requirements/authoring).

## Manual

For one-off additions:

<Steps>
  <Step title="Open Requirements">
    Dashboard → **Requirements → New Requirement**.
  </Step>

  <Step title="Fill the form">
    Required: `external_id`, `title`, `text`, `type`. Optional: `asil_pl`, `parent_id`, `tags`, `verification_method`.
  </Step>

  <Step title="Save">
    The requirement is created with `source: manual`. It behaves identically to other requirements — links, snapshots, audit trail.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

## 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`](https://github.com/roboticks-io/roboticks-sdk/blob/main/schemas/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

<CardGroup cols={2}>
  <Card title="ReqIF round-trip" icon="arrows-left-right" href="/requirements/reqif">
    Field mappings and re-export.
  </Card>

  <Card title="Authoring YAML" icon="pen" href="/requirements/authoring">
    Schema, types, ASIL annotations.
  </Card>

  <Card title="Hierarchy" icon="sitemap" href="/requirements/hierarchy">
    Parent / child rollup rules.
  </Card>

  <Card title="Snapshotting" icon="camera" href="/requirements/snapshotting">
    What freezes at release time.
  </Card>
</CardGroup>