NOVA app review
Review a customer robot application against the rule catalogue in references/rules/ and report
findings in chat. This is a read-only review: do not edit project files unless the user
asks for fixes afterwards.
Software rules are defence in depth. They never replace certified safety functions (safety
PLC, light curtains, SafeOperation, collaborative modes). Say so once in the report.
All paths below are relative to this skill's directory (the folder containing this file).
Workflow
Track these steps with a todo list.
1. Establish context
- Find the app root (the directory with
pyproject.toml / requirements.txt / .nova).
- Read the project's
AGENTS.md, CLAUDE.md or README.md if present.
- Note the installed SDK version:
uv run python -c "import importlib.metadata as m; print(m.version('wandelbots-nova'))"
(or the project's own interpreter). If an .installed-from.json file next to this SKILL.md
names a different wandelbots-nova version, tell the user to refresh the skill with
nova-skills install and continue with a note that SDK mappings may be stale.
2. Discover the architecture
Static search alone misses most safety findings. Locate and write down (file + line):
- entry point and event loop setup (
@nova.program, Novax, asyncio.run, FastAPI lifespan)
- robot connection / session lifecycle (
async with Nova(), cell.controller(...), motion group)
- motion entry points (
plan, execute, plan_and_execute, TrajectoryCursor)
- IO layer (controller IO
read/write/wait_for_bool_io, bus IO nova.utils.io, io_write)
- state machine or supervisor (modes, fault handling, reset)
- fault path (what happens between "error detected" and "robot stopped")
- shutdown path and signal handling
- job/program definitions and how they are selected
- device plugins (gripper, vision, force sensor, ...)
- configuration sources (env, config modules, datasets, PLC tag exports)
3. Run the scanner
uv run python <skill-dir>/scripts/scan.py <app-root> # or: python3 <skill-dir>/scripts/scan.py <app-root>
The scanner needs only the Python standard library. It prints JSON with:
candidates: {rule, severity, confidence, file, line, excerpt, message, path_kind}facts: project-wide signals (e.g. queries_tcp_names, uses_payload, nova_entry_points)
that rules use to decide whether a feature is missing
Candidates are hints, not findings. Confirm each one by reading the code. Drop false positives
silently; never report a candidate you have not confirmed.
4. Review every rule
Load the rule files for the areas you found in step 2. Load references/nova-sdk-mapping.md for
every NOVA-specific rule (scope: nova) and whenever the fix involves an SDK call. It lists the
SDK symbol to use, known SDK gaps and the recommended workaround for this SDK version.
| File | Rules |
|---|
references/rules/safety.md | SAF-001 … SAF-014 |
references/rules/motion.md | MOT-001 … MOT-013 |
references/rules/io.md | IO-001 … IO-007 |
references/rules/async.md | ASY-001 … ASY-009 |
references/rules/performance.md | PERF-001 … PERF-012 |
references/rules/lifecycle.md | LIFE-001 … LIFE-008 |
references/rules/errors.md | ERR-001 … ERR-006 |
references/rules/devices.md | DEV-001 … DEV-008 |
references/rules/configuration.md | CFG-001 … CFG-004 |
references/rules/observability.md | OBS-001 … OBS-005 |
references/rules/testing.md | TST-001 … TST-003 |
references/rules/structure.md | STR-001 … STR-003 |
references/nova-sdk-mapping.md | rule → SDK symbol, gaps, workarounds |
references/reference-numbers.md | measured timeouts and loop rates for sizing fixes |
Each rule has a detect hint: static (pattern is enough), review (read the control flow) or
static+review (search, then confirm by reading).
Skip rules that cannot apply (e.g. DEV-002 in a cell without vision) and list them as
"not applicable" in one line. Do not demand a feature the cell does not need.
5. Report in chat
Use the format below. Do not write a report file unless the user asks for one.
Severity
| Severity | Meaning | Gate |
|---|
error | Can injure people, damage hardware/parts, or leave the cell in an undefined state. | Block release |
warning | Measurable cycle-time loss, reliability risk, or recovery problems. | Fix before commissioning |
info | Maintainability, observability, ergonomics. | Backlog |
Raise severity by one level if the code path runs in automatic mode on real hardware; lower it
by one if it is provably simulation/test-only. State the adjustment in the finding.
False-positive guidance
- Tests, simulators and one-off scripts (
tests/, scripts/, tools/) may break performance and
async rules. Still report safety rules there if the script can move a real robot.
- Generated files (e.g. IO symbol modules) are exempt from naming/structure rules.
- A rule is satisfied if the requirement is met centrally (e.g. a shared
run_job() wrapper
that always returns home). Do not demand per-job duplication.
- Hardware safety is outside software scope.
- Code copied from SDK examples is not exempt: examples favour brevity over production rules.
Report format
## NOVA app review — <app name>
SDK: wandelbots-nova <version> · Scope: <dirs reviewed> · Rules checked: <n> · Not applicable: <ids>
> Software checks are defence in depth and do not replace certified safety functions.
| Severity | Count |
|---|---|
| error | n |
| warning | n |
| info | n |
### Top 5 fixes
1. RULE-ID — one line: what to change and why it matters most
### Safety
#### [ERROR] SAF-003 — Fault path stops motion first, with the shortest timeout
- **Location:** [app/supervisor.py](app/supervisor.py#L120-L134)
- **Evidence:** `await log_fault(...)` runs before the motion task is cancelled
- **Impact:** the robot keeps moving for the duration of the log call when a fault arrives
- **Fix:** cancel the execute task first, bounded by `asyncio.timeout(STOP_TIMEOUT_S)`; then log
```python
motion_task.cancel()
async with asyncio.timeout(STOP_TIMEOUT_S):
await asyncio.gather(motion_task, return_exceptions=True)
- Reference:
references/rules/safety.md (SAF-003); SDK: nova-sdk-mapping.md (SAF-003)
- Confidence: high
Motion
...
Rules for the report:
- Group findings by category in catalogue order; within a category order by severity.
- Every finding has file + line evidence. No evidence, no finding.
- **Fix** is the minimal concrete change, with a short code snippet where it helps. Use SDK symbols
from `nova-sdk-mapping.md`; never invent SDK APIs. If the SDK lacks a feature, say so and give
the workaround from the mapping.
- **Reference** names the rule file and rule ID, plus the SDK symbol or the SDK source/doc link
from the mapping.
- If the same violation repeats, report it once and list all locations.
- End with a short "Next steps" list and offer to apply the fixes.