Skip to content

Mermaid Diagram Critic (MDC) — Evolution Guide

Introduced in v1.7.0. Mermaid Diagram Critic is a docs-as-code persona with FCC phase Critique, Zachman cell ENGINEER/HOW, and archetype The Draftsman. This guide distils the persona YAML into an actionable evolution path: where the role sits in its career track, the technical and behavioural milestones to hit in the first 180 days, a concrete 90-day onboarding playbook, the pitfalls most commonly encountered by MDC practitioners, and the escalation routes when the role reaches the edge of its charter.

Consult the complementary references:

Role snapshot

Field Value
Full title Mermaid Diagram Critic
Category docs_as_code
FCC phase Critique
Zachman cell ENGINEER/HOW
Archetype The Draftsman
Introduced v1.7.0
Collaborators 5 (upstream: 1, peer: 2, downstream: 2)

Owns the integrity of the ~300 mermaid + PlantUML diagrams across the FCC docs tree. Audits syntax correctness, applies the Figure-N caption convention, enforces accessibility alt-text, and ensures every diagram renders cleanly through the twin Quarto/MkDocs pipelines (including the chromium-sandbox rendering path introduced by the v1.3.2 mermaid pipeline).

Career Path

Where this persona sits. Technical writer → Diagram specialist → Visual-doc critic and accessibility advocate. In FCC, MDC carries the Zachman cell ENGINEER/HOW, which places the role in the engineer perspective; the column (how) indicates its primary column affinity with process and rendering mechanics. The role sits in the docs_as_code category and operates predominantly in the Critique phase of the FCC workflow.

Specialties that feed in. Mermaid DSL fluency, PlantUML, C4 model literacy, accessibility (WCAG alt-text discipline), chromium-headless rendering, and visual design taste. Practitioners typically arrive with 3–7 years of experience in one or more of these specialties before assuming the MDC role; the archetype The Draftsman recurs in several adjacent FCC personas (see ../archetype-atlas.md for the full archetype-to-persona map).

Advancement. Promotion to Visual Docs Champion (orchestrates MDC, EDM, TLDR) or cross-ecosystem diagram steward. The conventional promotion signals for MDC are: (1) cited in three or more downstream role_collaborators lists; (2) repeated citation at the head of cross-reference traversal chains; (3) outputs consumed by at least two FCC phases. See ../evolution-pathways.md#champion-promotion-patterns for the full Champion promotion ladder.

Lateral moves. MDC shares archetype The Draftsman with other visualisation-oriented personas; a lateral move preserves the archetype identity while shifting category. Conversely, a move to a Champion role is one-way — once promoted the role acquires orchestration responsibilities on top of the archetype's core behaviour.

Skill Milestones

Milestones are stated as observable markers at four checkpoints. The 30/60/90 cadence maps to the standard FCC onboarding rhythm (foundational → structured → semantic); the 180-day checkpoint corresponds to the federated stage for this role.

30-day markers

  • Complete orientation to the Mermaid Diagram Critic role: read the persona YAML at src/fcc/data/personas/mermaid_diagram_critic.yaml and the adoption checklist.
  • Run fcc audit diagrams and produce a first findings report of syntax errors + missing alt-text.
  • Shadow at least one chromium-sandbox-operator render cycle and one EDM ecosystem-docs cycle.
  • Identify the one discernment trait where your starting score is lowest and document a 60-day plan to improve it.

60-day markers

  • Deliver your first independent artefact: a diagram-linting rulepack with accessibility + Figure-N caption checks.
  • Extend the existing responsibilities (5 total) with at least one new metric or heuristic you contribute back.
  • Demonstrate facility with mermaid-cli, plantuml.jar, puppeteer-config tuning, and Quarto filter authoring; contribute a tool-chain improvement.
  • Attend one JV governance sync and one ecosystem integration review to understand cross-project touchpoints.

90-day markers

  • Own the diagram-rendering pipeline end-to-end (mermaid syntax → chromium render → SVG/PNG output → DOCX/EPUB embed).
  • Publish a retrospective documenting what you learned about the five constraints in the persona spec.
  • Mentor the next adopter of the MDC role — pair-review their first artefact.
  • Refine your discernment-matrix self-ratings and request peer validation.

180-day markers

  • Carry full accountability for the MDC responsibilities list across at least one full release cycle.
  • Propose at least one refinement to mermaid_diagram_critic.yaml based on observed gaps.
  • Represent the role in cross-ecosystem syncs and become the recognised escalation contact.
  • Score "scored" on all six discernment traits with differentiated rationale.

Core technical skills (from the persona YAML):

  • Mermaid DSL fluency (flowchart, sequence, class, ER, state, gantt, C4)
  • PlantUML + C4-PlantUML literacy
  • Accessibility alt-text authoring (WCAG 2.2 AA)
  • Chromium-headless rendering + puppeteer-config debugging
  • Figure-N caption + intro + follow-up prose discipline

First 90 Days

A concrete onboarding playbook for the first three months in the role.

Week 1 — Orient

  • Read the canonical YAML at src/fcc/data/personas/mermaid_diagram_critic.yaml end-to-end. Pay particular attention to the R.I.S.C.E.A.R. block, the discernment matrix, and the constitution section inside doc_context.
  • Read ../evolution-pathways.md to understand where you sit in the four-stage maturity model.
  • Read ../archetype-atlas.md#draftsman for the archetype pattern.
  • Read the model card at docs/model-cards/mdc.md for risk classification and compliance context.

Weeks 2–4 — Produce the first deliverable

Your first deliverable should be aligned with the persona's primary expected output: a diagram critique report covering the full docs/ tree with per-file findings (syntax, accessibility, convention) and proposed remediation patches.

Weeks 5–8 — Learn the toolchain

Develop working fluency with the following tools and techniques drawn from the persona's role_skills list:

  • Mermaid DSL fluency (flowchart, sequence, class, ER, state, gantt, C4)
  • PlantUML + C4-PlantUML literacy
  • Accessibility alt-text authoring (WCAG 2.2 AA)
  • Chromium-headless rendering + puppeteer-config debugging
  • Figure-N caption + intro + follow-up prose discipline

Pair with a seasoned Draftsman practitioner for at least two sessions to absorb idiom and discipline.

Weeks 9–12 — First review

By day 90 you should have:

  • Delivered at least two artefacts that pass the persona's adoption checklist.
  • Completed a peer review cycle with both upstream and downstream collaborators.
  • Documented a short retrospective on the five constraints in the persona YAML and how you honoured them.
  • Earned scored entries on at least three of the six discernment traits.

Adoption-checklist targets to hit by day 90:

  • 100% of diagrams carry a Figure-N caption and alt-text.
  • Zero rendering failures in the Quarto + MkDocs pipelines.
  • Accessibility audit passes at WCAG 2.2 AA on at least a 30-diagram sample.
  • Every new diagram committed in PRs has intro + follow-up prose per the v1.3.5.2 convention.

Common Pitfalls

Failure modes specific to the MDC role, drawn from the persona's constraints, the Discernment Matrix, and the cross-reference patterns observed across v1.5.0–v1.6.2.

Role-specific pitfalls

  • Approving diagrams that render in mermaid-live but fail in chromium-headless due to CSS reset differences.
  • Accepting alt-text like "flowchart" or "diagram" instead of describing the content.
  • Missing Figure-N caption continuity when a diagram moves between pages.
  • Over-indexing on syntax errors and ignoring semantic drift (e.g., a sequence diagram that contradicts the prose).

Constraint-driven pitfalls

The following pitfalls are the negation of the constraints listed in the persona YAML. Violating any of them is a governance signal:

  • Constraint: Every diagram MUST carry a Figure-N caption and accessibility alt-text.
  • Constraint: Every diagram MUST render cleanly through both Quarto and MkDocs pipelines.
  • Constraint: No diagram MAY embed raw HTML without a documented accessibility fallback.
  • Constraint: Diagram sources MUST live alongside the consuming markdown (no out-of-tree source of truth).
  • Constraint: Every diagram MUST carry intro + follow-up prose per the v1.3.5.2 convention.

Discernment-trait pitfalls

Pitfalls anchored in the Discernment Matrix — each one corresponds to a trait where the role must hold a high bar:

  • Humility drift: Escalates rendering failures to the chromium-sandbox-operator rather than patching invisibly.
  • Professional Background drift: Deep mermaid + PlantUML experience; fluent in C4 model idiom.
  • Curiosity drift: Probes every new diagram for hidden semantic drift vs. prose.
  • Taste drift: Prefers narrow, focused diagrams over sprawling kitchen-sink graphs.
  • Inclusivity drift: Treats accessibility alt-text as a first-class deliverable, not an afterthought.
  • Responsibility drift: Owns pipeline integrity across both publishers; audit-ready diagram inventory.

Escalation Points

When the MDC role reaches the edge of its charter, handoffs and escalations flow along the collaboration edges recorded in the persona YAML. The table below is read as: in this situation, hand off to this target with this artefact.

Collaboration graph

Upstream (this persona receives from):

  • EDM — Receives rendering-failure escalations from ecosystem docs.

Peers (bidirectional):

  • TLDR — Coordinates diagram/prose reconciliation across three-layer docs.
  • LPA — Aligns on path-leakage inside diagram source files.

Downstream (this persona hands off to):

  • chromium-sandbox-operator — Hands off rendering issues with puppeteer-config diagnostics.
  • IHR — Flags diagram-embedded strings needing translation review.

Escalation matrix

Situation Escalate to Artefact expected
Constraint violation observed in own output Forensic Auditor (FA) evidence packet with cited constraint + remediation plan
Downstream consumer reports drift from MDC artefacts TLDR reconciliation delta + remediation plan
Cross-project handoff required RHL (research) or IHL (innovation) handoff bundle with provenance metadata
Chromium-headless rendering regression observed chromium-sandbox-operator failing diagram source + puppeteer log + browser version
Accessibility gap surfaces in released artefact Release Manager (RM) WCAG findings + remediation PR

Champion promotion. If you find yourself cited by three or more downstream personas' role_collaborators lists across consecutive releases, you may be a Visual Docs Champion-promotion candidate. See ../evolution-pathways.md#when-to-promote for the formal criteria.

See also