How to Redraw Mermaid Imports and Track Changes with the Fidelity Ledger

Redraw Mermaid imports by extracting a structural intermediate representation, applying four configuration dials, and rebuilding the diagram from scratch while the fidelity ledger documents every merge, collapse, or drop operation.

The cathrynlavery/diagram-design repository provides a specialized workflow for converting Mermaid source files into editorial-quality diagrams. Unlike simple format conversion, the redraw Mermaid imports procedure discards all original layout and styling to rebuild diagrams according to a strict design system. This process includes a comprehensive fidelity ledger that transparently reports every structural transformation applied during the redraw.

Understanding the Mermaid Import Redraw Procedure

The Mermaid import workflow treats conversion as a redraw rather than a direct translation. According to skills/diagram-design/references/import-mermaid.md, the process parses the source Mermaid file—whether .mmd, .mermaid, or fenced blocks in Markdown—into a language-agnostic intermediate representation (IR).

This IR contains only structural data: labels, directives, and URLs are treated as plain text without execution or rendering. The system then rebuilds the diagram from this IR, ignoring all original Mermaid-specific layout, themes, or class information. The result is a diagram that conforms to the skill's design system rather than the original rendering.

The Six-Step Redraw Workflow

The complete procedure is defined in skills/diagram-design/references/import-mermaid.md and consists of six sequential steps:

1. Extract the IR
   Run skills/diagram-design/scripts/mermaid_extract.py to parse the source into the structural IR. No JavaScript execution, rendering, or network calls occur during this phase.

2. Set the Four Dials
   Configure --format, --size, --detail, and --audience before drawing begins. These parameters drive the final output dimensions, abstraction level, and vocabulary style according to skills/diagram-design/references/output-spec.md.

3. Pick the Target Type
   Map the detected Mermaid grammar (such as flowchart, sequenceDiagram, stateDiagram-v2, or erDiagram) to the appropriate diagram type (Flowchart, Architecture, Sequence). Record any manual overrides.

4. Build the Semantic Model
   Transform the IR into a story-centric model: name the narrative, apply the selected detail level, choose focal nodes, and rewrite labels for the target audience while preserving essential edge labels and container relationships.

5. Redraw from Blank
   Initialize a blank viewBox using the size preset. Apply the semantic model while ignoring all Mermaid-specific layout or styling. Route connections according to the connector rules defined in SKILL.md, without adding decorative filler components.

6. Deliver and Report
   Emit a self-contained HTML file as the source of truth, optionally generate SVG/PNG outputs, and produce the fidelity ledger enumerating every merge, collapse, or drop operation.

How the Fidelity Ledger Works

When the output contains fewer nodes than the input—which occurs in balanced or simplified detail levels and most faithful runs—the system generates a fidelity ledger as specified in section 5 of skills/diagram-design/references/output-spec.md. This ledger makes information loss explicit and transparent.

Ledger Entry Format

Each ledger entry follows a structured pattern documenting the transformation:

Detail: balanced · 18 source nodes → 9 drawn
Merged:  worker-01..06 → "Ingest Worker ×6"
Collapsed: "Observability" group (Grafana, Loki, Tempo) → one node
Dropped: 2 sticky notes, CI pipeline (cross‑cutting)
Kept in full: the request path (Client → Gateway → Orders → Postgres)

Types of Transformations

The ledger categorizes changes into five specific types:

• Detail: Shows the detail level used and the node count reduction (e.g., "18 source nodes → 9 drawn").
• Merged: Identical nodes condensed into a single representative with a multiplier (e.g., api‑worker‑01..04 → "API Worker ×4").
• Collapsed: Container groups where all children are leaves represented by the parent container alone.
• Dropped: Decorative elements, degree-1 sinks, or cross-cutting infrastructure removed by the degrade ladder.
• Kept in full: Core story elements that survived unchanged, confirming narrative preservation.

Running the Import Workflow

Command-Line Execution

Invoke the extractor script directly to process Mermaid files:

python3 skills/diagram-design/scripts/mermaid_extract.py diagrams/architecture.mmd \
    --diagram all --detail balanced --size slide-16x9 --format html \
    --output diagrams/out

This command parses all fenced blocks (--diagram all), applies the balanced detail level, configures a slide-sized canvas, and emits HTML output.

Pi Command Interface

For integrated workflows, use the Pi command template defined in commands/import-mermaid.md:

/diagram-design:import‑mermaid diagrams/architecture.mmd --size=slide-16x9 --detail=balanced

The Pi backend executes mermaid_extract.py, applies the four dials automatically, generates the requested outputs, and returns the fidelity ledger in the chat interface after the file path.

Verification and Testing

The scripts/verify-mermaid-import.py test harness validates that the extractor and ledger logic comply with the specification in skills/diagram-design/references/import-mermaid.md. Run this to ensure fidelity reporting accuracy before production deployment.

Summary

• Redraw Mermaid imports convert source files to IR and rebuild from scratch, discarding original layout and themes.
• The fidelity ledger documents every structural change when node counts decrease, categorized as Merged, Collapsed, Dropped, or Kept.
• Four dials (--format, --size, --detail, --audience) control output characteristics and must be set before drawing begins.
• HTML output serves as the source of truth, with optional SVG/PNG derivatives.
• Source code resides in cathrynlavery/diagram-design, with core logic in skills/diagram-design/scripts/mermaid_extract.py and specifications in skills/diagram-design/references/import-mermaid.md.

Frequently Asked Questions

What is the difference between redrawing and converting Mermaid diagrams?

Redrawing extracts only structural data into an intermediate representation and rebuilds the diagram according to the skill's design system, ignoring all original Mermaid layout, themes, and styling. Converting typically implies preserving the original rendering with format changes, which this workflow explicitly avoids to ensure editorial quality.

When does the fidelity ledger appear in the output?

The fidelity ledger appears whenever the output contains fewer nodes than the input source, which occurs in balanced or simplified detail levels and most faithful runs. According to skills/diagram-design/references/output-spec.md, the ledger is mandatory for these reductions to maintain transparency about omitted elements.

Can I override the automatically detected diagram type?

Yes. Step 3 of the workflow allows overriding the detected Mermaid grammar (such as flowchart or sequenceDiagram) when the content demands a different diagram type. Any override must be recorded in the workflow documentation to maintain auditability.

How do I verify that the extractor and ledger are working correctly?

Run the scripts/verify-mermaid-import.py test harness, which validates that skills/diagram-design/scripts/mermaid_extract.py and the fidelity ledger logic comply with the canonical procedure in skills/diagram-design/references/import-mermaid.md. This ensures accurate parsing and transformation reporting.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}