Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / diagram-diagnostics

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:

  1. It resolves python3 first and then python. The selected interpreter must report version 3.10 or newer.
  2. 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.
  3. In maintainer-checkout mode, it checks the expected verification scripts.
  4. In maintainer-checkout mode, it checks that command and prompt files point to their matching reference files.
  5. 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

TriggerConsequenceGuard
The doctor searches for SKILL.md relative to the user's projectA healthy installed skill is reported as missingResolve the skill from the loaded installation context and accept a standalone SKILL.md root
python3 is present as a non-running aliasA working python fallback is missed and readiness fails too earlyProbe the version and fall through to python when the first name cannot answer
Playwright imports but the default Chromium or headless shell cannot startPNG export cannot render the source HTMLBound 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 modeRepository verification coverage is incompleteFail the expected-script check and restore the named script
A command or prompt does not point to its referenceUser entry points can drift from the source instructionsFail the routing-surface check and restore the matching reference path
A check command exits unexpectedlyLater checks and the final report are lostCapture stderr, classify the result, and continue the ordered checks
--strict is treated as a new status typeAutomation can ignore warnings that should block readinessKeep WARN in the report but return a failing exit code when warnings exist

Key files

FileWhy to read it
skills/…/doctor.mdDefines the diagnostic goal, modes, checks, safety rules, and output contract
commands/doctor.mdDefines the Claude command route and its read-only behavior
prompts/doctor.mdDefines the Pi prompt route and installation-resolution requirement
scripts/verify-doctor.pyVerifies readiness checks, status aggregation, strict exits, and JSON reporting
scripts/test-verify-doctor.pyExercises fallback, mode separation, routing failures, and report edge cases
skills/…/self_check.pyDefines the separate artifact gate for safe, accessible, and usable generated HTML
scripts/verify-geometry.pyCovers connector and label geometry that the doctor does not inspect
skills/…/SKILL.mdPlaces diagnostics within the central design, output, and validation workflow