/simulink-requirements

name: simulink-requirements
description: Use this skill for all requirements-related work in a MATLAB MBSE project using the Requirements Toolbox (slreq). Covers creating and populating requirement sets, derivation links, test case requirements, verification coverage, reading and tracing links across requirement sets and models, checking link health, allocating requirements to components (Implement links), and building traceability reports. Trigger when the user asks about slreq API, slreqx files, slmx link files, outLinks/inLinks, traceability matrices, coverage analysis, broken links, or mapping requirements to architecture components. Use proactively for any requirements or traceability task.
license: MathWorks BSD-3-Clause (see LICENSE)
metadata:
  author: MathWorks
  version: "1.0"

MATLAB Requirements Toolbox — Requirements & Traceability

This skill covers everything in the `slreq` API: creating and reading requirements, managing traceability links, checking verification coverage, allocating requirements to architecture components, and auditing link health.

For architecture phases (System Composer models, functional decomposition, functional→physical allocation) see the `mbse-architecture` skill.

See `references/api-quickref.md` in this skill folder for a compact one-page API reference.

---

The Two File Types

| Extension | Class | Role | |---|---|---| | `.slreqx` | `slreq.ReqSet` | Stores requirements (text, hierarchy) | | `.slmx` | `slreq.LinkSet` | Stores traceability links **outgoing from a source artifact** |

When a `.slmx` file is created

slreq writes a `.slmx` file **only when its companion artifact is the source of at least one link.** The LinkSet is keyed on the source artifact, not the destination.

• `MyReqs~slreqx.slmx` appears only if some link's source is a requirement in `MyReqs.slreqx` (e.g., `slreq.createLink(srcReq, destReq)` where `srcReq` lives in `MyReqs`)
• `MyModel~mdl.slmx` appears only if some link's source is a model element in `MyModel.slx` (typical: `slreq.createLink(component, req)` with Type `Implement` — the component is the source)

An artifact that is only ever a link *destination* never gets a paired `.slmx`. In a typical MBSE project:

| Artifact | Gets a `.slmx`? | Why | |---|---|---| | `StakeholderNeeds.slreqx` | Yes | SNs are the source of Derive links to SRs | | `SystemRequirements.slreqx` | **Usually no** | SRs are destinations of Derive / Implement / Verify links; no file unless SR-to-SR Refine links or links to external docs are added | | `TestCases.slreqx` | Yes | TC requirements are the source of Verify links to SRs | | Architecture `.slx` models | Yes | Components are the source of Implement links to SRs |

Reporting rules for build scripts

Because `.slmx` files are conditional, **never claim a `.slmx` was produced based on the API calls you made — always verify with `isfile` before reporting.** A script that creates only SN→SR Derive links will produce `StakeholderNeeds~slreqx.slmx` but **not** `SystemRequirements~slreqx.slmx`, even though both `.slreqx` files exist.

Idempotent cleanup and project registration for `.slmx` files must both guard with `isfile`:

if isfile(snLinks), delete(snLinks); end   % cleanup — safe whether or not it exists

The `registerWithProject` helper already does this — it skips files that don't exist on disk — so passing a non-existent `.slmx` path is a no-op, not an error.

---

Requirements (Phases 1–2)

---

Two-Level Structure

| Level | ID scheme | Character | |---|---|---| | Stakeholder Needs | `SN-SYS-001` | Operational, informal — what the user/operator needs | | System Requirements | `SR-SYS-001` | Formal, testable — what the system shall do |

Each SR traces back to one or more SNs via a `Derive` link.

---

Well-Formed Shall-Statements

• One obligation per requirement ("shall", not "should" or "will")
• Measurable and testable — include numeric criteria where possible
• Avoid `<` and `>` in Description fields — the Requirements Editor treats them

as HTML. Use "not exceeding", "at least", "greater than", etc.

**Good:** `The system shall respond with latency not exceeding 100 ms.` **Avoid:** `The system shall respond with latency < 100 ms.`

---

Creating Requirement Sets

slreq.clear();
if isfile('MyReqs.slreqx'), delete('MyReqs.slreqx'); end
rs = slreq.new('MyReqs.slreqx');        % NOT slreq.createReqSet (does not exist)

req = rs.add();
req.Id          = 'SR-SYS-001';
req.Summary     = 'Short title';
req.Description = 'The system shall ...';
req.Rationale   = 'Why this requirement exists.';

rs.save();

Find a requirement by ID

req = rs.find('Id', 'SR-SYS-001');

---

Valid Link Types

| Type | Meaning | Direction | |---|---|---| | `"Derive"` | Parent decomposes into derived child | SN (source) → SR (destination) | | `"Implement"` | Architecture element (or model block) implements requirement | Component/Block (source) → SR (destination) | | `"Verify"` | Test case verifies requirement | TC (source) → SR (destination) | | `"Refine"` | Requirement refined into a more specific requirement (same artifact kind, more detail). Not used for SR → architecture in this workflow. | SR (source) → SR (destination) | | `"Relate"` | Informal relationship | Bidirectional |

---

Creating Links

% Req-to-req derivation: parent (e.g. SN) decomposes into derived child (e.g. SR)
lnk = slreq.createLink(parentReq, childReq);
lnk.Type = 'Derive';

% Model block to req (model must be open in Simulink)
lnk = slreq.createLink(blockHandle, req);
lnk.Type = 'Implement';

% Test case requirement to SR
lnk = slreq.createLink(tc, sr);
lnk.Type = 'Verify';

slreq.saveAll();   % always call after creating cross-artifact links

Side effect: `{modelName}~mdl.slmx` link store

The first time you create a link whose **source** is an element of a Simulink/System Composer model (component, subsystem, or block), slreq write