Diagram diagnostics
Diagram diagnostics provide a read-only readiness check for the Diagram Design skill. The doctor command confirms that the runtime, optional PNG export support, installed skill, and maintainer wiring are usable, while artifact checks remain the responsibility of the skill-local and repository validation flows.
Diagnostic scope
The doctor is an environment check, not a visual review. It answers whether the current host can route Diagram Design commands and support the main import and export paths.
Environment readiness
The user-facing /diagram-design:doctor and /doctor routes follow commands/doctor.md, which sends the command to skills/…/doctor.md. That reference is the source of truth for the check order, status rules, safety limits, and report shape. The command can run from a normal project directory because it resolves the installed skill rather than treating the current directory as the skill repository.
The doctor never installs packages, edits files, or runs destructive Git actions. If one check fails, it records the error and continues so the report shows the full readiness picture.
References: commands/doctor.md• L10-22 prompts/doctor.md• L6-18 skills/…/doctor.md• L1-17 skills/…/doctor.md• L111-116
Artifact boundaries
The doctor does not prove that a diagram communicates well or that its HTML is safe and accessible. Use Diagram self-validation for generated artifact checks, and use the relevant import or repository verification flow when a checked-in example or source conversion is involved.
This boundary keeps environment failures separate from diagram failures. A host can be ready while an artifact has bad SVG naming or connector geometry. An artifact can also be valid while the host lacks the browser support needed to export a PNG.
References: skills/…/doctor.md• L5-9 skills/…/doctor.md• L43-49 skills/…/self_check.py• L214-365 scripts/verify-geometry.py• L1-30
Doctor workflow
The doctor follows one ordered path from runtime discovery to a human report. It chooses the installed-skill or maintainer-checkout view before it judges repository-only resources.
flowchart LR
A[Doctor command] --> B[Resolve Diagram Design skill]
B --> C[Select diagnostic mode]
C --> D[Check Python runtime]
D --> E[Check Playwright and Chromium]
E --> F{Maintainer checkout?}
F -->|Yes| G[Check scripts and command wiring]
F -->|No| H[Mark maintainer checks not applicable]
G --> I[Check common path mistakes]
H --> I
I --> J[Print summary and check statuses]
J --> K{Warnings or failures?}
K -->|Yes| L[Print Next actions]
K -->|No| M[Finish]
Installation resolution
The resolution step locates the Diagram Design installation from the loaded skill context. It accepts either a repository layout with skills/…/SKILL.md or a standalone skill root with SKILL.md. The current project directory is not used as evidence that the installation is missing.
The mode then depends on three maintainer markers: CONTRIBUTING.md, .github/…/ci.yml, and scripts/verify-plugin-package.py. When all three exist under the resolved root, the doctor adds repository checks. Otherwise it uses installed-skill mode and does not report missing maintainer files as defects.
References: skills/…/doctor.md• L7-17 skills/…/doctor.md• L84-92 scripts/verify-doctor.py• L21-28 scripts/verify-doctor.py• L241-255
Check sequence
The doctor runs the checks in a fixed order so a later result can use an earlier result without hiding the cause of a failure:
- It resolves
python3first and thenpython. The selected interpreter must report version 3.10 or newer. - It checks that Playwright imports in that interpreter and that the default headless Chromium can launch for PNG export. Missing support is a warning because the host can provision it later.
- In maintainer-checkout mode, it checks the expected verification scripts.
- In maintainer-checkout mode, it checks that command and prompt files point to their matching reference files.
- It checks common path mistakes, including a missing resolved SKILL.md and Windows paths with quoting risk.
The doctor probes whether a command can actually run. A name on PATH that cannot report its version does not block fallback to the next Python name, and an unlaunchable command becomes a reported failure instead of stopping the run. Browser startup and its probe have time limits, and the doctor reports cleanup problems rather than leaving the run open-ended.
References: skills/…/doctor.md• L28-92 scripts/verify-doctor.py• L68-126 scripts/verify-doctor.py• L409-419
Report contract
Every report starts with a compact summary and then gives one status line for each check. The overall result is PASS when all checks pass, WARN when warnings exist without failures, and FAIL when any check fails. Next actions appears only when a warning or failure has a recorded fix.
The optional --strict flag keeps the check statuses unchanged but makes warnings return a failing process exit code. The optional --json flag appends a machine-readable object with the overall status, counts, check details, timestamp, strict-mode state, and host context.
References: skills/…/doctor.md• L94-110 scripts/verify-doctor.py• L351-406 commands/doctor.md• L14-22
Readiness modes
The two modes serve different readers. Installed-skill mode helps a diagram author fix the host that runs the skill, while maintainer-checkout mode helps a repository owner detect missing verification and routing surfaces.
Installed-skill mode
Installed-skill mode checks only resources needed by a user of the installed skill. Python is a hard requirement, while Playwright and Chromium affect PNG export readiness. Maintainer scripts and repository command trees are explicitly not applicable, so their absence does not create a false failure for an ordinary project directory.
This mode is the normal first-run path. A warning about Playwright means HTML and other supported work may still be possible, but PNG export needs an approved renderer and browser in the host environment.
References: skills/…/doctor.md• L11-17 skills/…/doctor.md• L43-49 skills/…/doctor.md• L50-61 scripts/verify-doctor.py• L257-277
Maintainer-checkout mode
Maintainer-checkout mode adds repository readiness to the runtime checks. It requires the shipped import, motion, skin, and documentation verification scripts, then confirms that the Claude command files and Pi prompt files route to the references they claim to use.
These checks protect the contract between user-facing entry points and the longer reference documents. A missing file or a stale reference path is a hard failure because the repository can appear to expose a feature that no longer has a valid instruction path.
References: skills/…/doctor.md• L50-82 scripts/verify-doctor.py• L30-50 scripts/verify-doctor.py• L257-316
Verification workflow
The repository verifies the doctor as a readiness tool rather than as a diagram renderer. The verifier exercises the status model and the edge cases that can make a host look healthy when it is not.
Doctor verifier
The maintainer utility at scripts/verify-doctor.py is the repository-side check for doctor behavior. It uses the same broad surfaces as the reference: Python resolution, Playwright readiness, maintainer markers, required scripts, routing surfaces, common path checks, summary status, and optional JSON output.
The companion scripts/test-verify-doctor.py runs adversarial cases. It confirms that missing scripts and stale routing fail, a standalone installation does not require maintainer files, broken python3 resolution can fall through to python, strict mode elevates warnings to a failing exit code, and reports retain the summary and JSON contract.
References: scripts/verify-doctor.py• L100-190 scripts/verify-doctor.py• L241-348 scripts/verify-doctor.py• L351-443 scripts/test-verify-doctor.py• L71-230
Readiness handoff
Use the doctor before import or export work when the host state is uncertain. After readiness passes, follow the diagram workflow: choose the communication fit and semantic type in Diagram taxonomy and semantic patterns, apply the project skin from Diagram style and visual primitives, and use Diagram onboarding and output contract for the source and delivery rules.
The wider Diagram Design skill provides the parent workflow. For motion, also check Diagram animation. For the generated file or imported source, continue with Diagram self-validation. The doctor is an entry check in this larger flow; it does not replace any of these artifact or design decisions.
References: skills/…/doctor.md• L5-9 skills/…/doctor.md• L111-116 scripts/test-verify-doctor.py• L204-230
Change checklist
When these files or sections are changed, remember to consider these:
- If the doctor reference changes its check order, status meanings, or output fields, keep commands/doctor.md, prompts/doctor.md, and the verifier aligned with that contract.
- If skill resolution or maintainer markers change, keep installed-skill mode separate from maintainer-checkout mode so normal project directories do not fail on repository-only files.
- If Python fallback or Playwright probing changes, preserve the downstream interpreter handoff, browser probe limits, and the rule that missing browser support never triggers an install.
- If command or prompt routing changes, update the expected routing map and its maintainer verification together.
- If JSON fields change, keep human output, strict exit behavior, and machine-readable output consistent.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The doctor searches for SKILL.md relative to the user's project | A healthy installed skill is reported as missing | Resolve the skill from the loaded installation context and accept a standalone SKILL.md root |
python3 is present as a non-running alias | A working python fallback is missed and readiness fails too early | Probe the version and fall through to python when the first name cannot answer |
| Playwright imports but the default Chromium or headless shell cannot start | PNG export cannot render the source HTML | Bound browser and subprocess probes, report a warning with a browser provisioning fix, and do not auto-install |
| A maintainer-only script is missing in checkout mode | Repository verification coverage is incomplete | Fail the expected-script check and restore the named script |
| A command or prompt does not point to its reference | User entry points can drift from the source instructions | Fail the routing-surface check and restore the matching reference path |
| A check command exits unexpectedly | Later checks and the final report are lost | Capture stderr, classify the result, and continue the ordered checks |
--strict is treated as a new status type | Automation can ignore warnings that should block readiness | Keep WARN in the report but return a failing exit code when warnings exist |
Key files
| File | Why to read it |
|---|---|
| skills/…/doctor.md | Defines the diagnostic goal, modes, checks, safety rules, and output contract |
| commands/doctor.md | Defines the Claude command route and its read-only behavior |
| prompts/doctor.md | Defines the Pi prompt route and installation-resolution requirement |
| scripts/verify-doctor.py | Verifies readiness checks, status aggregation, strict exits, and JSON reporting |
| scripts/test-verify-doctor.py | Exercises fallback, mode separation, routing failures, and report edge cases |
| skills/…/self_check.py | Defines the separate artifact gate for safe, accessible, and usable generated HTML |
| scripts/verify-geometry.py | Covers connector and label geometry that the doctor does not inspect |
| skills/…/SKILL.md | Places diagnostics within the central design, output, and validation workflow |