---
name: build-and-simulate
description: Use when building, simulating, testing on device, or running the CG Mobile app (wraps `sf mdl build`, `sf mdl simulate`). Parses common build and runtime errors and points at the failing artifact. Auto-invoked at the end of any workflow skill.
---

# Build and Simulate — CG Mobile Modeler

## When to use this skill

-   User says: "build", "simulate", "test on device", "run the app"
-   Other skills invoke this: `add-cockpit-card`, `add-list-screen`, `add-detail-screen`, `add-calendar-view`, and optionally any foundation skill after file creation
-   NOT for: writing new artifacts (use the relevant `create-*` skill first)

## Prerequisites

-   Repo root contains ``
-   `sf` CLI is on PATH (`sf --version` succeeds)
-   Modeler plugin is installed (`sf mdl --help` succeeds)

Confirm both before running build:

```bash
sf --version && sf mdl --help > /dev/null && echo OK
```

If either fails, stop and instruct the user to install the modeler plugin per `ai-wiki/wiki/modeler-setup.md` (if present) or the project README.

## Mandatory checklist

-   [ ] `# cd to your workspace root` before any `sf mdl` command
-   [ ] Build before simulate — never skip `sf mdl build`
-   [ ] Read the full build output, not just the last line (warnings can hide real failures earlier)
-   [ ] If simulate fails, check browser/devtools console for runtime errors (see `references/common-errors.md`)

## Core commands

```bash
# cd to your workspace root

# Clean previous build artifacts
sf mdl clean

# Build all contracts
sf mdl build

# Run local simulator (opens browser)
sf mdl simulate
```

## Failure mode 1: build fails with "DataSource not found"

**Symptom:** `ERROR: DataSource 'DsLoVisitsOpen' not found`
**Diagnosis:** A BO or LO references a DS that doesn't exist.
**Fix:** Grep for the name:

```bash
grep -rn 'name="DsLoVisitsOpen"' src/
```

If no match, create the DS (invoke `create-datasource`). If a match exists with a typo, fix the typo at either end.

## Failure mode 2: build passes, simulate crashes on SQLITE_ERROR

**Symptom:** Browser shows `SQLITE_ERROR: no such column: Status` in the console.
**Diagnosis:** A DS declares a column not present in `appl/data/app.db3`.
**Fix:** Invoke the `verify-sqlite-schema` skill with the table and column name.

## Failure mode 3: build passes, simulate shows blank screen

**Symptom:** Page loads but the target card/list is empty with no error.
**Diagnosis:** Usually a BL method is not returning data, or a process is stuck on a DECISION branch.
**Fix:**

1. Open devtools console — check for `Uncaught TypeError`
2. Add `ApplicationContext.log(...)` at the suspected BL entry point
3. Rebuild and re-run

## Failure mode 4: "Cannot read properties of undefined (reading 'Load')"

**Symptom:** Runtime crash with this exact message.
**Diagnosis:** DS has mismatched `external` attribute vs content.
**Fix:** Open the DS named in the stack trace. If it has `<QueryCondition>`, `external="false"`; if `<Database><Load>`, `external="true"`. See `create-datasource` skill.

## Failure mode 5: long build time / stale build

**Symptom:** Build finishes quickly but behavior still matches an old version.
**Fix:**

```bash
sf mdl clean && sf mdl build
```

## Execution flow (for workflow skills invoking this)

1. Run `sf mdl build`
2. If build fails, parse stderr for the patterns above and report which artifact to fix
3. If build passes, optionally run `sf mdl simulate` (ask user first — it opens a browser)
4. Return to the caller with status: `build_ok` / `build_failed:<artifact>` / `simulate_launched`

## Escape hatch

For errors not in this skill: see `references/common-errors.md` or `ai-wiki/wiki/testing-and-build.md` (if available).

## Verify

This skill is verified by running it against a known-good state and a known-bad state. See `tests.md`.
