mx-doctor

name

mx-doctor

description

Mendix project health check. Read-only. Wraps `mx check` (Mendix's bundled validator) plus mxcli's lint/report passes. Surfaces errors, warnings, deprecations, performance concerns, security flags, and convention violations -- triaged by severity. Auto-invoke before any commit / push of a Mendix project, after pulling someone else's changes, and after any auto-conversion (mx convert). Also invocable as /mx-doctor.

mx-doctor

Read-only project health snapshot. The "what's wrong with this Mendix project right now" primitive. Combines two authoritative sources:

• mx check -- Mendix's own bundled validator. Always trustworthy.
• mxcli lint + mxcli report -- Starlark-rule-driven linting and 6-category scoring. Trustworthy within the limits of mxcli's alpha state; treat findings as hints, not gospel.

North star

Find the breakage before Studio Pro shows it to you in the morning.

When to invoke

Auto-invoke when:

• About to commit / push a Mendix project. (Pre-codex hook for Mendix work.)
• Just pulled someone else's changes and haven't opened Studio Pro yet.
• Just ran mx convert (version upgrade can introduce new deprecations).
• Investigating a "Studio Pro won't open the project" symptom.

Do not invoke for:

• Single-question lookups ("what does this microflow do").
• Brand-new project with one entity (nothing to check).

What it does

1. Verify environment.

   • mx --version available? (Bundled with Studio Pro at C:\Program Files\Mendix\<version>\modeler\mx.exe. If multiple Studio Pro versions installed, prefer the one matching the project per mx show-version <project>.mpr.)
   • mxcli --version available? If not, mark mxcli passes as SKIP and proceed with mx check only.
   • cwd has *.mpr? If not, abort with a clear message.

2. Run authoritative pass:

   • mx check <project>.mpr -- collect errors, warnings, deprecations, performance recommendations.

3. Run mxcli passes (if available):

   • mxcli lint -- Starlark-rule findings.
   • mxcli report -- 6-category scoring (security / architecture / quality / design / best practices / conventions).

4. Synthesize the report:

## /mx-doctor

**Project:** <name> at <path>
**Mendix version:** <version> (matching `mx` binary: <yes|no -- see warning>)

### `mx check` findings (authoritative)

**Errors (N):** <-- this section is the gate; non-zero = do not commit -->
- <file:position> -- <error>

**Warnings (N):**
- <file:position> -- <warning>

**Deprecations (N):**
- <file:position> -- <what's deprecated> -- <suggested replacement if known>

**Performance recommendations (N):**
- <file:position> -- <recommendation>

### mxcli lint (advisory)

**Security:** <count by severity>
**Architecture:** <count>
**Quality / Design / Best practices / Conventions:** <count>

Top 5 mxcli findings (if any):
- <file:position> -- <category> -- <finding>

### Verdict
- COMMIT-OK (zero `mx check` errors)
- COMMIT-BLOCKED (mx check errors present)
- COMMIT-OK-WITH-WARNINGS (zero errors, but high warning/deprecation count -- consider cleanup)

### Triage suggestion
- <if BLOCKED: which error to fix first and why>
- <if WARNINGS: top-3 worth addressing>

5. Stop. Read-only. No writes.

Hard rules

• Treat mx check errors as commit-blockers. They will surface in Studio Pro the next time the project opens. Better to fix now.
• Treat mxcli findings as advisory, not authoritative. mxcli is alpha. If mx check and mxcli lint disagree, trust mx check.
• Always report version mismatch. Running mx check with a different Studio Pro version than the project was last opened with is a known source of false positives.
• Do not propose fixes inline. This is a triage report, not a remediation skill. Suggested approach goes in the verdict; actual fixes belong to follow-up work.
• Read-only, period. Never run mxcli's write subcommands from this skill, even on a finding that would obviously be fixed by a write.

Cross-reference

• Pre-push gate: ~/.claude/skills/pre-codex/SKILL.md (general); this skill is the Mendix specialization.
• Discovery: ~/.claude/skills/mx-discover/SKILL.md, impact: ~/.claude/skills/mx-impact/SKILL.md.
• Mendix specialist: ~/.claude/agents/mendix-expert.md.