Source: Dev.to

Visualising Workflows with Mermaid

“A picture says a thousand words.”
I wanted to see my system—not the code, but the workflows that drive it.
What happens when a rule gets validated? When a session starts? When compaction triggers?

---

The Problem with Prose‑Only Workflows

• Readability collapses after a few branching steps.
• Returning weeks later forces a full re‑parse of dense paragraphs.
• LLMs suffer from the “lost in the middle” effect: they handle information at the start and end of a context well, but struggle with critical logic buried in the middle.
• Drift: removing or renaming a pipeline phase often leaves stale references in prose, breaking the flow silently.

---

The Solution: Mermaid Flowcharts

I rewrote my workflows as Mermaid diagrams and observed three immediate benefits:

1. Instant visual map – rendered diagrams give a clear, at‑a‑glance view of the system.
2. Higher LLM fidelity – structured syntax stands out in a context window full of prose, so Claude (and other agents) follow the steps more reliably.
3. Self‑maintaining – dangling arrows are impossible; missing steps become obvious.

%% Example placeholder – replace with your actual diagram
graph TD
    A[Start] --> B{Rule validated?}
    B -- Yes --> C[Proceed]
    B -- No --> D[Log error]
    D --> E[Notify user]
    C --> F[End]

---

Supporting Research

FlowBench (Xiao et al., EMNLP 2024) evaluated LLM agents given the same workflow knowledge in three formats:

Takeaway: Format matters—structured diagrams dramatically improve an agent’s ability to follow instructions.

---

When to Use Diagrams vs. Prose

Rule of thumb: If it has branches, it needs a diagram. If it requires judgment, add prose.

---

Example: Rule‑Validation Workflow (Prose‑Only)

Below is the original prose description of my rule‑validation workflow, before I switched to a diagram.

[Insert your original prose here]

---

Next Steps

1. Convert existing prose workflows to Mermaid diagrams.
2. Pair diagrams with concise prose for any judgment or contextual notes.
3. Version‑control both the .md files and the generated diagrams to keep them in sync.

By visualising the system, you gain a clearer mental model, reduce LLM errors, and keep your workflows from “rotting” over time.

Rule Validation

Run validation on all rules. For each rule:

1. Schema validation – check fields, types, and format.
2. Contract validation – ensure the .md and .yml files match.
3. Template resolution – substitute any template variables.
4. OpenGrep validation – test the pattern syntax.

• If OpenGrep exits with 2 or 7, treat it as a failure and report the error.
• If it exits with 0 or 1, the rule passes.

After every rule has been processed, output a summary of the results.

---

Flowchart (Mermaid)

flowchart TD
    START([/validate-rules options]) --> COLLECT[Collect rules from paths]
    COLLECT --> LOOP[For each rule]
    LOOP --> SCHEMA[1. Schema validation
Fields, types, format]
    SCHEMA -->|fail| REPORT
    SCHEMA -->|pass| CONTRACT[2. Contract validation
.md and .yml matching]
    CONTRACT -->|fail| REPORT
    CONTRACT -->|pass| RESOLVE[Resolve template variables]
    RESOLVE --> OPENGREP[3. OpenGrep validation
Pattern syntax]
    OPENGREP -->|exit 2 or 7| REPORT
    OPENGREP -->|exit 0 or 1| REPORT[Report results]
    REPORT --> NEXT{More rules?}
    NEXT -->|yes| LOOP
    NEXT -->|no| SUMMARY[Summary output]

---

Result

The flowchart makes every branch explicit and shows each failure path, so nothing can be inadvertently skipped or mis‑interpreted (e.g., which OpenGrep exit codes constitute a failure).

---

Example Workflow

Below is a trimmed excerpt from an actual workflow file (rule‑validation.md) used in the Reporails project. It demonstrates how the steps above are combined with other formats (e.g., YAML snippets, shell commands) to create a complete, reproducible validation pipeline.

# rule-validation.md

## Overview
Validate all rule definitions in `rules/` against the official schema and contract.

## Steps
1. **Collect rules**
   ```bash
   find rules/ -name "*.yml" > rule-list.txt

2. Schema validation

   while read -r file; do
       yamllint -d "{extends: default, rules: {line-length: {max: 120}}}" "$file" \
           || echo "Schema error in $file"
   done  resolved.yml

3. OpenGrep validation

   opengrep -p pattern.resolved.yml
   case $? in
       0|1) echo "Pattern OK" ;;
       2|7) echo "Pattern error" ;;
   esac

4. Summary

   echo "Validation complete – see logs for details."

---

By combining markdown for documentation, YAML for data, shell snippets for execution, and a Mermaid diagram for visual flow, the workflow is both human‑readable and machine‑executable. This multi‑format approach is what FlowBench identified as the most effective way to convey complex validation logic.

Rule Validation Workflow

flowchart TD
    START([/validate-rules options]) --> COLLECT[Collect rules from paths]
    COLLECT --> LOOP[For each rule]
    LOOP --> SCHEMA[1. Schema validation
Fields, types, format]
    SCHEMA -->|fail| REPORT
    SCHEMA -->|pass| CONTRACT[2. Contract validation
.md and .yml matching]
    CONTRACT -->|fail| REPORT
    CONTRACT -->|pass| RESOLVE[Resolve template variables]
    RESOLVE --> OPENGREP[3. OpenGrep validation
Pattern syntax]
    OPENGREP -->|exit 2 or 7| REPORT
    OPENGREP -->|exit 0 or 1| REPORT[Report results]
    REPORT --> NEXT{More rules?}
    NEXT -->|yes| LOOP
    NEXT -->|no| SUMMARY[Summary output]

Why Three Layers in This Order

flowchart TD
    A[Schema validation] -->|passes| B[Contract validation]
    B -->|passes| C[OpenGrep validation]
    A -->|fails| D[Stop processing]
    B -->|fails| D
    C -->|fails| D
    style A fill:#e0f7fa,stroke:#006064,stroke-width:2px
    style B fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style C fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style D fill:#ffebee,stroke:#b71c1c,stroke-width:2px

Rationale

1. Schema validation – This is the cheapest check because it only inspects the structure of the files (missing fields, wrong types) and has no external dependencies. It filters out rules that would cause confusing downstream failures.

2. Contract validation – After we know both files are structurally sound, we verify that rule.md and rule.yml are in agreement. This catches the class of bugs where one file was updated but the other wasn’t.

3. OpenGrep validation – The most expensive step. It runs the actual patterns against the syntax checker, requiring template resolution, file I/O, and agent‑config loading. It is only executed on rules that have already passed the first two layers.

The ordering follows the principle “cheapest first, most expensive last,” and each layer depends on the previous one being clean. This ensures a predictable, efficient pipeline.