mbse-workflow

What this skill does

# MBSE Workflow — Guided Project Setup and Phase Orchestration

This skill walks through an MBSE project one phase at a time — for greenfield
setup *and* for resuming an existing project mid-workflow. At each phase:
propose → get approval → generate script → run it → checkpoint. If the user
rejects or wants changes, revise and regenerate — scripts are idempotent so
this is always safe.

## Skills by phase (at-a-glance routing)

| Phase | Domain skill | What it covers |
|---|---|---|
| 0 | `matlab-project` | `.prj` setup, folder layout, file tracking, build-script conventions, `runChecks` |
| 1, 9 | `simulink-requirements` | `slreq` API — SNs, SRs, TCs; Derive / Implement / Verify links; coverage |
| 2–4 | `mbse-architecture` (+ `system-composer`) | F / L / P models, three-level interface dictionaries |
| 4b–c | `mbse-architecture` / `system-composer` | Stereotype profile, architecture views (review dashboards) |
| 5–7 | `mbse-architecture` | F→L and L→P allocation sets, SR Implement links per layer |
| 8 | `mbse-architecture` | Quantitative roll-up analysis, margins (optional) |
| 10 | this skill | `buildAll.m`, project health check |

**Builds on `matlab-project`** for the generic `.prj` mechanics: project
creation, file tracking, path management, `removeFile`-before-`delete`,
build-script idempotency conventions, and `runChecks` health checks. This
skill generates the MBSE phase content; the project plumbing follows the
patterns in [`../matlab-project/SKILL.md`](../matlab-project/SKILL.md).

Use the other `mbse-*` skills for technical API patterns at each phase. This
skill manages the conversation flow and script generation.

---

## Project folder layout

The MBSE project layout follows the standard `setupProject` shape from
`matlab-project`, with these subfolders:

```
my-system/
├── my-system.prj          MATLAB Project file
├── plan.md / decisions.md (living docs — see below)
├── requirements/          .slreqx files (StakeholderNeeds, SystemRequirements, TestCases)
├── architecture/          .slx, .sldd, .xml, .mldatx (model, dictionary, profile, allocation)
├── analysis/              .mat (analysis instances)
├── verification/          (reserved — TC artifacts currently live in requirements/)
├── scripts/               buildAll.m, all phase build scripts, setupProject + setupMBSEProject
└── derived/               build outputs — NOT tracked in the project
    ├── cache/
    └── codegen/
```

---

## Cross-Phase Dependencies

- **Architecture rebuilds break allocation links.** `slreq.createLink` stores
  component references by Simulink SID. If you rebuild the model, SIDs change
  and Implement allocation links become stale. Always rebuild allocation after
  rebuilding the architecture model.

- **Profile setup belongs in the architecture script.** Create and apply the
  stereotype profile at the end of `buildPhysical()` so estimates travel with the
  model and survive every rebuild.

- **`slreq.saveAll()` saves cross-set links.** Call it after any session that
  creates links between different `.slreqx` files or between requirements and
  architecture artifacts.

- **`slreq.clear()` unloads all sets from memory** but does not delete files.
  Call it at the top of each script for a clean slate, then `slreq.load()` the
  files you need.

- **Delete `.slmx` link files alongside `.slreqx` files** when rebuilding
  requirement sets. Stale `.slmx` files store cross-artifact links and will
  auto-open old model files on load, causing conflicts.

---

## How to conduct this session

Work through the phases in order. Never jump ahead. At each checkpoint, present
what you are about to create in plain language and wait for explicit approval
("looks good", "yes", "proceed") before generating the script. If the user
asks for changes, make them and re-present — do not generate until approved.

After running each script, show the MATLAB output and ask the user to confirm
it looks right before moving to the next phase. Keep proposed content concise
and specific — avoid vague placeholders.

---

## Living documentation: `plan.md` and `decisions.md`

This skill **overrides** the generic living-doc framework from `matlab-project`
with MBSE-flavored templates. The framework, cadence guidance, and
when-to-append rules live in [`../matlab-project/SKILL.md`](../matlab-project/SKILL.md);
this skill ships its own templates with RFLPV phase rows and MBSE-specific
sections (Engineering concerns, Analysis scope, Decision context).

Use the templates at
[`templates/plan.md`](templates/plan.md) and
[`templates/decisions.md`](templates/decisions.md) — **not** the generic ones
under `matlab-project/templates/`. Phase 0 copies both into the project root,
fills placeholders from the interview answers, and registers them with the
MATLAB project so they travel with the repo. Subsequent phases edit them per
the cadence in `matlab-project`.

---

## Phase 0: Interview and Project Setup

Ask the following questions (can be in one message):

1. **System name** — what is the system called? (Used for file and model names, e.g. `SatComSystem`)
2. **Project location** — full path to the folder where the project should be created
3. **System description** — one paragraph: what does it do, what problem does it solve?
4. **Requirements source** — do you already have system requirements in an Excel/xlsx file, or should we develop them together in the interview? (determines Phase 1 Path A vs. Path B below)
5. **Key engineering concerns and review views** — two linked sub-questions, ask together:
   - (a) What *properties* of components matter for design decisions? (e.g. mass, power, cost, reliability, latency, data rate, supplier, safety level — these become stereotype properties applied to every physical component.)
   - (b) What *filtered views* of the architecture would help during review? (e.g. "components costing more than 10% of the cost budget", "all safety-critical components", "components supplied by vendor X", "components consuming > 20 kW", "any component with a zeroed estimate — a forgotten-input flag".) Each view is either a stereotype-property query (`Cost > 150000`, `SafetyLevel == 'DAL-A'`, `Supplier == 'VendorX'`) or an allocation-driven hand-picked list ("all components realizing ControlUnit").
   - **(a) and (b) are linked.** A view filters on a property, so every property the user wants to view by must appear on the stereotype. If they want a by-supplier view, add a `Supplier` property. If they want a safety-critical view, add `SafetyLevel`. Ask (b) before finalising (a); the answers together determine the stereotype scope.
6. **Analysis needs** — is any quantitative roll-up or trade study analysis needed? If so, what kind?
7. **Decision context** — anything about the decision context here that isn't obvious from the SRs? Past incidents that shape risk tolerance, organizational constraints, dependent programs, stakeholder or political considerations. This answer seeds `decisions.md` with meaningful backstory so later design choices have the "why" captured alongside the "what".

**Do not ask the user for physical subsystems up front.** The physical
architecture is *derived* from the functional architecture, the logical
architecture, and the SRs — not specified a priori. If the user volunteers a
physical decomposition, note it but do not commit to it; the Phase 4 proposal
must still be driven by what the L→P mapping and hardware-specific SRs require.

After gathering answers, create the MATLAB Project inline (not as a saved
script — the `scripts/` folder doesn't exist yet). Use the MBSE wrapper
[`code/setupMBSEProject.m`](code/setupMBSEProject.m), which pins the RFLPV
folder set on top of `setupProject` from `matlab-project`:

```
setupMBSEProject(projectName, projectFolder)
```

The wrapper expands to:

```matlab
setupProject(projectName, projectFolder, ...
    {'requirements','architecture','analysis','verification','scripts'}, ...
    {fullfile('derived','cache'), ful