vt-c-diagram-validate¶

Post-render validation gate for Mermaid diagrams. Inspects rendered PNG output against 6 quality criteria, auto-revises on failure (max 3 attempts), and recommends PlantUML for complex diagrams. Use after diagram rendering or as part of the diagram pipeline.

Plugin: core-standards
Category: Other
Command: /vt-c-diagram-validate

Diagram Auto-Validation Gate¶

Inspect rendered diagram output for quality issues and trigger auto-revision when criteria fail. Designed to be invoked after vt-c-mermaid-diagrams-branded or vt-c-mermaid-to-images renders a diagram.

When to Use¶

After rendering any Mermaid diagram to PNG
As part of the /vt-c-docs-pipeline-orchestrator pipeline
Before including diagrams in final documents (PDF/Word)

Invocation¶

/vt-c-diagram-validate diagram.png                # Validate a rendered diagram
/vt-c-diagram-validate diagram.png --source diagram.mmd  # Validate with source for revision
/vt-c-diagram-validate --count 12                  # Pre-render element count check only
/vt-c-diagram-validate --skip                      # No-op (pipeline compatibility)

Execution Instructions¶

Step 1: Parse Arguments¶

Extract from invocation: - Image path — PNG file to validate (required unless --count or --skip) - --source {path} — Mermaid source file for auto-revision (optional) - --count {N} — element count for pre-render format check (skip to Step 2 only) - --skip — exit immediately with no output (pipeline compatibility)

If --skip: exit 0 immediately.

Step 2: Element Count Check (Pre-Render)¶

If --count is provided OR if --source is provided (count elements from source):

Count the number of diagram elements (nodes, actors, classes, states) in the Mermaid source.

Routing by count:

Elements	Action
< 5	"Small diagram — Mermaid is ideal. Proceed." Skip count advisory.
5-9	"Mermaid OK for this complexity." Proceed to Step 3.
10-15	AskUserQuestion: "This diagram has {N} elements. Mermaid may produce a dense layout. Use Mermaid (simpler) or PlantUML (better layout for complex diagrams)?"
> 15	"Complex diagram ({N} elements). PlantUML recommended for better layout." Check if `plantuml` is available via `which plantuml`. If not available: "PlantUML not installed — proceeding with Mermaid. Consider installing PlantUML for complex diagrams." (EC-3)

If --count only (no image path): display result and exit. Otherwise: proceed to Step 3.

Step 3: Post-Render Quality Inspection¶

Read the rendered PNG image using the Read tool (Claude's vision capability).

Evaluate against 6 quality criteria:

Criterion 1: Element Accuracy¶

Are all expected nodes/boxes from the source visible in the rendered image?
If source provided: compare node count in source vs visible elements in image
Score: PASS if all elements visible, FAIL if any missing

Criterion 2: Relationship Completeness¶

Are all connections/arrows from the source visible?
Check for edges that may have been clipped by the render boundary
Score: PASS if all relationships visible, FAIL if connections missing

Criterion 3: Layout Readability¶

Is text legible at rendered scale? (no tiny, unreadable labels)
Are elements spaced adequately? (no overlapping boxes or cramped clusters)
Score: PASS if readable, FAIL if text is too small or elements overlap

Criterion 4: Abstraction Level¶

Does the diagram maintain a consistent level of detail?
Flag if high-level architecture boxes are mixed with implementation-level details
Score: PASS if consistent, WARN if mixed (non-blocking)

Criterion 5: Style Consistency¶

For VisiTrans-branded diagrams: verify orange (#FC9E00) and black (#000000) are present
Check font consistency (no mixed font sizes for same-level elements)
Score: PASS if consistent, WARN if minor inconsistencies (non-blocking)

Criterion 6: Edge Crossing¶

Count visible line crossings in the diagram
Score: PASS if ≤5 crossings, FAIL if >5 (indicates layout needs restructuring)

Display validation result:

Diagram Validation: {filename}
─────────────────────────────────────────────────────────────
  [PASS] Element accuracy      — all {N} elements visible
  [PASS] Relationships         — all connections rendered
  [FAIL] Layout readability    — overlapping labels detected
  [PASS] Abstraction level     — consistent detail level
  [PASS] Style consistency     — VisiTrans CD colors present
  [PASS] Edge crossings        — 3 crossings (≤5 threshold)

  Result: 5/6 PASS — revision needed
─────────────────────────────────────────────────────────────

If all 6 criteria PASS (WARNs are acceptable): display "Validation PASSED" and exit.

If any criterion FAILs: proceed to Step 4 (if source provided) or display failures and exit.

Step 4: Auto-Revision Loop¶

Requires --source flag (Mermaid source file path). Without source, report failures and exit — cannot auto-revise.

Path validation: Before modifying the source file, verify: 1. The file exists and is readable 2. The file extension is .mmd, .mermaid, or .md (reject other extensions) 3. The file is within the current project directory (reject absolute paths outside the working tree)

If validation fails: report "Cannot auto-revise: source file {path} is not a valid Mermaid file or is outside the project." and exit without modification.

Loop (max 3 attempts per NFR-2):

attempt = 1
while attempt <= 3 and validation has FAILs:

  1. Analyze specific failures:
     - Layout readability FAIL → suggest direction change (TB→LR or LR→TB)
     - Edge crossing FAIL → suggest reordering node declarations
     - Element accuracy FAIL → check for Mermaid syntax issues
     - Relationship completeness FAIL → check for edge syntax errors

  2. Modify the Mermaid source file with targeted fixes

  3. Re-render the diagram:
     - Use mmdc CLI: mmdc -i {source} -o {output} -t dark
     - Or delegate to /vt-c-mermaid-to-images

  4. Re-validate (Step 3)

  5. Log attempt:
     "Attempt {attempt}/3: {pass_count}/6 criteria passed. Failures: {list}"

  attempt += 1

If all 3 attempts exhausted with remaining FAILs (EC-2):

⚠ Auto-revision did not fully resolve quality issues after 3 attempts.

Best attempt: Attempt {N} ({pass_count}/6 criteria passed)
Remaining issues:
  - {failure 1 description}
  - {failure 2 description}

The best attempt has been kept as the output file.
Consider manual adjustment of the Mermaid source.

Step 5: Validation Log¶

After each validation (pass or fail), output a structured log entry:

Diagram Validation: {filename}
  Attempt: {N}/3
  Criteria: {pass_count}/6 passed ({warn_count} warnings)
  Failures: {list of failed criteria}
  Action: PASS | REVISED | ACCEPT-WITH-WARNING

Revision Strategies¶

When auto-revising, apply these targeted fixes based on the failure type:

Failure	Strategy
Overlapping labels	Change layout direction: `graph TB` → `graph LR` (or vice versa)
Too many edge crossings	Reorder node declarations to minimize crossings
Cramped spacing	Add `%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px'}}}%%`
Missing elements	Check for Mermaid syntax errors (unclosed brackets, missing arrows)
Split recommendation	For >20 nodes: suggest splitting into 2 sub-diagrams with a connecting overview

Relationship to Other Skills¶

Skill	Relationship
`/vt-c-mermaid-diagrams-branded`	Primary caller — invokes validation after rendering
`/vt-c-mermaid-to-images`	Re-rendering engine for auto-revision loop
`/vt-c-markdown-diagram-processor`	Can invoke validation during doc pipeline
`/vt-c-docs-pipeline-orchestrator`	Orchestrates the full pipeline including validation