generate-requirement-drafts

# Generate Requirement Drafts Generate draft requirements from Simulink models using the richest artifact the environment supports. All outputs are **drafts** requiring human review and approval before baselining. ## When to Use - Drafting or updating requirements from a Simulink model - Creating `.slreqx` or `.yaml` requirements artifacts - Establishing model-to-requirement traceability ## When NOT to Use - Importing requirements from an existing source of truth (ReqIF, DOORS, Word, Excel) — use Requirements Toolbox import APIs directly - Writing or running tests — use the `testing-simulink-models` skill - Free-form prose notes with no saved artifact - User explicitly wants a different text format (markdown, Word) ## Output Conventions - Default file names: `<Model>_Requirements.slreqx` or `<model>_requirements.yaml` - Stable IDs: `REQ_<SYSTEM>_001`, `REQ_<SYSTEM>_002`, … — use **one** consistent project-wide prefix with sequential integers across all requirements, even when they derive from different subsystems. Do not switch to per-subsystem prefixes or hierarchical decimal numbering (e.g. `CB-1.1`, `TP-1.1`). - Follow repo conventions if `.slreqx` or `.yaml` files already exist - When updating an existing artifact, preserve existing IDs — append new IDs, never renumber - Every generated requirement must be marked as draft — use `"draft"` in Keywords (slreq) or `status: Draft` + `keywords: [draft]` (YAML) ## Writing Good Requirements Requirements must express **behavioral intent** (WHAT the system shall do), not restate model topology (HOW it is implemented). Put the WHY in `Rationale`. Use **EARS (Easy Approach to Requirements Syntax)** patterns: ### EARS Patterns Choose the pattern that best fits the model behavior: | Pattern | Template | When to Use | |---------|----------|-------------| | **Ubiquitous** | The \<system\> shall \<response\>. | Always-on behavior, invariants | | **Event-driven** | When \<trigger\>, the \<system\> shall \<response\>. | A momentary trigger causes a one-time response: input events, **entering** a Stateflow state (the transition itself) | | **State-driven** | While \<state\>, the \<system\> shall \<response\>. | Behavior that holds continuously **while in** a Stateflow state or mode — the ongoing response, not the entry transition | | **Unwanted behavior** | If \<condition\>, then the \<system\> shall \<response\>. | Error handling, safety limits, saturation | | **Optional feature** | Where \<feature\>, the \<system\> shall \<response\>. | Variant subsystems, configurable features | | **Combined** | While \<state\>, when \<trigger\>, the \<system\> shall \<response\>. | State + event combinations | ### Examples — Model Concepts to EARS Requirements | ❌ Bad — restates implementation | ✅ Good — EARS pattern | |---|---| | "Saturation block limits output to [0,1]" | "If throttle command exceeds ThrottleMax (1.0) or falls below ThrottleMin (0.0), then the controller shall clamp the output to the valid range." | | "BrakeLogic subsystem disengages controller" | "When brake pedal input exceeds BrakeThreshold (0.0), the controller shall disengage cruise control." | | "Gain block multiplies by 2.5" | "While cruise control is active, the controller shall amplify speed error by Kp (2.5) to compute proportional correction." | | "Stateflow chart transitions to Idle" | "When the driver presses the off button, the system shall transition to the Idle state." | | "Defrost state runs the heater at full power" | "While in the Defrost state, the system shall drive the heater at full power." | | "Variant subsystem selects Algorithm A" | "Where the adaptive mode is enabled, the controller shall use the predictive algorithm." | ### Rules - Write requirements using **EARS patterns** — pick the pattern that matches the model behavior - Use block/subsystem names (e.g. `Saturation`, `BrakeLogic`) only in `Rationale`, `Description`, or provenance notes — **never** in the requirement `Summary`. (A workspace *parameter* rendered as `VarName (value)` is required in the Summary and is not a block name.) - When referencing a numeric value, include the **workspace variable name and resolved value**: `VarName (value)`. If the model uses a literal with no variable, record the numeric literal directly - Put the **WHY** in `Rationale`, not in the requirement statement - One subsystem may support zero, one, or several behavioral requirements — don't force a 1:1 mapping - For a Stateflow state or mode, separate **entering** it from **being in** it: the entry transition is event-driven (`When <trigger>, … shall transition to <state>`), but the behavior that holds throughout the mode is state-driven (`While <state>, … shall <response>`). When asked for a mode's behavior, prefer the `While <state>` form — do not fold it into a `When` entry statement ## Backend Decision Gate Choose once at the start, then stay on that path. | Situation | Backend | |-----------|---------| | User explicitly asks for `.slreqx`, traceability views, or repo already uses `.slreqx` | **Requirements Toolbox** — if probe fails, **inform the user** that Requirements Toolbox is unavailable; do NOT silently fall back | | User explicitly asks for `.yaml`, or repo already uses `.yaml` requirements | **Structured YAML** | | No format specified — probe for Requirements Toolbox | **Requirements Toolbox** if probe succeeds | | No format specified and probe fails | **Structured YAML** (silent fallback is OK here since user had no preference) | **Probe** (run via `evaluate_matlab_code`): ```matlab hasSlreq = ~isempty(which('slreq.new')); if hasSlreq, try, slreq.find(Type="Link"); catch, hasSlreq = false; end, end disp(hasSlreq) ``` ## Workflow - Call `model_overview`, `model_read`, `model_query_params`, `model_resolve_params` as **MCP tools** — never pass their names to `evaluate_matlab_code`. - Use `evaluate_matlab_code` only for MATLAB code, such as the backend probe and the `slreq.*` APIs in Path A. 1. **Understand the model** — use the `model_overview` and `model_read` tools to understand subsystems, interfaces, control logic. 2. **Extract parameters** — use the `model_query_params` / `model_resolve_params` tools for thresholds, gains, sample times that should appear in requirement text. Record both variable names and resolved values. 3. **Build a capture table** (backend-neutral): | Id | ParentId | Summary | Description | SourceBlock | Rationale | ASIL | Priority | Keywords | |----|----------|---------|-------------|-------------|-----------|------|----------|----------| 4. **Run the backend path** (A or B below). 5. **Review** using the gate below. ### Path A — Requirements Toolbox (`.slreqx`) Use when probe succeeds. For full API patterns see `references/slreq-patterns.md`. ```matlab model = "CruiseControl"; load_system(model); rs = slreq.new(model + "_Requirements"); % Add requirements with hierarchy — note behavioral "shall" statements req = add(rs, Id="REQ_CC_001", ... Summary="If throttle command exceeds ThrottleMax (1.0) or falls below ThrottleMin (0.0), then the controller shall clamp the output to the valid range.", ... Description="Derived from CruiseControl/ThrottleCmd."); req.Rationale = "Prevents invalid actuator commands that could damage the throttle body."; req.Keywords = ["draft","auto-generated","control","safety"]; child = add(req, Id="REQ_CC_002", ... Summary="When brake pedal input exceeds BrakeThreshold (0.0), the controller shall disengage cruise control.", ... Description="Derived from CruiseControl/BrakeLogic."); child.Keywords = ["draft","auto-generated","safety","brake"]; % Create traceability links: use block handle from SID (blk_X → X) for robustness lnk = slreq.createLink(Simulink.ID.getHandle(model + ":5"), req); slreq.createLink(Simulink.ID.getHandle(model + ":8"), child); save(rs); % Save all link sets linkSets = slreq.find(Type="LinkSet"); for i = 1:numel(linkSets), save(linkSets(i)); end ``` **Link rules:** - Source = model element, destination = requirement → link type is automatically `Implement` - Prefer subsystem-level links; use block-level only when the requirement is block-specific - Every model-derived requirement **must** have at least one traceability link - The model **must** be loaded (`load_system`) before creating links with block paths ### Path B — Structured YAML fallback Use when Requirements Toolbox is unavailable. For schema and field rules see `references/yaml-requirements.md`. 1. Generate a `<model>_requirements.yaml` file from the capture table 2. Set `status: Draft` and include `draft` in `keywords` for every requirement 3. Self-review: all required fields set, `asil`/`status`/`priority` use valid values, IDs sequential, `derived_from` references valid IDs or is `null` 4. Validate: ```bash python -c "import yaml, sys; yaml.safe_load(open(sys.argv[1])); print('OK')" path/to/requirements.yaml ``` ## Guardrails | Always | Never | |--------|-------| | Mark every generated requirement as **DRAFT** | Emit markdown or ad hoc text when `.slreqx` is available and no text format was requested | | Write requirements using EARS patterns | Restate block topology as the requirement summary | | Include parameter name + value: `VarName (value)` | Create both `.slreqx` and `.yaml` unless user asks for both | | Link direction: model element → requirement | Reverse the link direction (requirement → block) | | `load_system` before creating traceability links | Over-link every primitive block — prefer subsystem links | | Use only R2023a+ APIs | Silently fall back to YAML when user explicitly requested `.slreqx` | | Stay consistent with existing repo format | Renumber existing requirement IDs on regeneration | ## Review Gate Before finishing, verify (both backends): - [ ] Every requirement has `Id`, `Summary`, and `Description` - [ ] Every requirement is marked as **DRAFT** (via Keywords or status field) - [ ] Summaries use EARS patterns, not block-topology restatements - [ ] Numeric values include parameter name + value where a workspace variable exists - [ ] IDs are stable and sequential; existing IDs preserved on regeneration **slreq path only:** - [ ] Model-derived requirements have a traceability link to the source model element - [ ] Link direction is model element → requirement (not reversed) - [ ] Subsystem-level linking preferred over block-level - [ ] Requirement set and all link sets are saved **YAML path only:** - [ ] File parses without errors - [ ] `asil` and `priority` use valid enum values (or `Unset` when unknown) ## References - `references/slreq-patterns.md` — Requirements Toolbox API cookbook - `references/yaml-requirements.md` — Structured YAML schema and field rules - `assets/slreq_from_model.m` — End-to-end slreq example - `assets/requirements.yaml` — Structured YAML example ---- Copyright 2026 The MathWorks, Inc. ----