feat(diagrams): add communication quality gates (#364)

Add audience, narrative, hierarchy, representation, accessibility, uncertainty, review evidence, and eval coverage for C4 and Mermaid artifacts.\n\nAI-assisted: Jasper orchestrated implementation and verification with OpenCode.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

.claude-plugin/marketplace.json

@@ -156,7 +156,7 @@
         "./c4-diagramming"
       ],
       "strict": false,
-      "description": "Create C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need clear system context, container, component, or code-level views."
+      "description": "Create and review C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need a communication-ready system context, container, component, or code-level view, including audience, narrative, hierarchy, labels, legends, accessibility, and uncertainty. Do not use for Mermaid syntax/rendering work without C4 modeling, architecture decisions, or full accessibility conformance reviews."
     },
     {
       "name": "capacity-and-cost-engineering",
@@ -669,7 +669,7 @@
         "./mermaid-diagrams"
       ],
       "strict": false,
-      "description": "Author, render, and troubleshoot Mermaid diagrams for documentation, architecture, processes, and technical communication. Use when a text-based diagram needs to stay versionable."
+      "description": "Author, render, troubleshoot, and review Mermaid diagrams for documentation, architecture, processes, and technical communication. Use when a versionable diagram must communicate a defined audience job across a real renderer, including narrative, hierarchy, labels, legends, accessibility fallback, and uncertainty. Do not use for C4 level/model ownership, architecture decisions, or full accessibility conformance."
     },
     {
       "name": "meshcore-packet-capture",

c4-diagramming/README.md

@@ -13,11 +13,11 @@ Use it when the work needs a repeatable process and an inspectable result. It is
 | Path | What it provides |
 |---|---|
 | `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. |
-| `references/` | Reference material: `architecture-as-code-ecosystem.md`, `c4-to-pyramid-mapping.md`, `ci-pipeline-templates.md` |
+| `references/` | Reference material for C4 levels, architecture-as-code tooling, CI, and communication review, including `technical-diagram-communication.md`. |
 
 ## Quick Start
 
-Choose the C4 level and authoring format in `SKILL.md`, then load the matching reference before drawing.
+Choose the C4 level and authoring format in `SKILL.md`, load the matching reference before drawing, and review the rendered artifact for the audience's job rather than syntax alone.
 
 Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below.
 
@@ -25,6 +25,7 @@ Install or expose this directory using your agent's standard Agent Skills loadin
 
 - Create C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need clear system context, container, component, or code-level views.
 - Requests involving the method, deliverables, or review process described in `SKILL.md`.
+- Requests to make a C4 diagram understandable to a particular audience or to review its hierarchy, narrative, labels, uncertainty, or accessible fallback.
 - Work where a reusable template or reference from this skill would reduce avoidable mistakes.
 
 ## Requirements

c4-diagramming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: c4-diagramming
-description: Create C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need clear system context, container, component, or code-level views.
+description: Create and review C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need a communication-ready system context, container, component, or code-level view, including audience, narrative, hierarchy, labels, legends, accessibility, and uncertainty. Do not use for Mermaid syntax/rendering work without C4 modeling, architecture decisions, or full accessibility conformance reviews.
 license: MIT
 compatibility: Mermaid or Structurizr tooling is optional and only needed to render or validate diagrams.
 metadata:
@@ -24,6 +24,16 @@ C4 Model for structural architecture visualization. Produces diagrams at four zo
 
 C4 is the cleanest structural fit — its four-level hierarchy maps to the three pyramid layers with almost no translation, and Levels 2-3 both resolve to separate L2 analysis files.
 
+## Communication Gate
+
+Before choosing notation or polishing layout, state the audience and the job the reader must complete. Select one C4 level that answers that job; do not mix system context, container, component, and code claims merely to fill a canvas. Keep the abstraction level, element vocabulary, boundary treatment, and relationship meaning consistent within a view. A structurally valid C4 model can still be the wrong communication artifact if it asks the reader to infer the purpose, mixes levels, hides important paths, or overwhelms the intended reader.
+
+Load `references/technical-diagram-communication.md` when creating, revising, or reviewing a diagram for a real audience. Use its review record to check narrative/read order, visual hierarchy, labels and legends, signal-to-noise, color-independent meaning, accessibility handoff, uncertainty, and review evidence. Full accessibility conformance remains owned by `web-accessibility`; architecture decisions remain owned by `software-architecture`.
+
+## Review Evidence
+
+Record the intended audience and question, C4 level and scope, key claim, known uncertainty, target renderer, and an accessible text or tabular fallback. Review both the source model and the rendered artifact. A passing syntax/model validator proves structural validity only; it does not prove that the diagram communicates the intended claim.
+
 ## Authoring Formats
 
 ### Mermaid (Default for Quick Diagrams)
@@ -67,7 +77,7 @@ Full reference in `references/architecture-as-code-ecosystem.md` — tool compar
 ## Contents
 
 - `references/c4-to-pyramid-mapping.md` — context→L1, container/component→L2, code→L3 (Mermaid + Structurizr DSL paths)
-- `references/c4-to-flowchart.md` — (in `mermaid-diagrams` skill) C4 → standard flowchart conversion patterns for GitHub compatibility
+- [`c4-to-flowchart.md`](../mermaid-diagrams/references/c4-to-flowchart.md) — companion Mermaid conversion patterns for GitHub-compatible flowcharts
 - `references/architecture-as-code-ecosystem.md` — Structurizr DSL, C4-PlantUML, docToolChain, converged repo convention, tool comparison table
 - `references/ci-pipeline-templates.md` — GitHub Actions, GitLab CI, ForgeJo (Gitea Actions, Woodpecker) pipeline templates for Structurizr validation, export, deploy
 
@@ -84,7 +94,7 @@ GitHub's built-in Mermaid renderer does **not** bundle the C4 plugin (`@mermaid-
 - `Rel()` → `-- label -->` or `-.->`
 - Drop `UpdateLayoutConfig()` — use `flowchart LR` or `TB` directive instead
 
-For the full conversion table with worked examples, load `references/c4-to-flowchart.md` from the companion `mermaid-diagrams` skill when it is available.
+For the full conversion table with worked examples, load [`c4-to-flowchart.md`](../mermaid-diagrams/references/c4-to-flowchart.md) from the companion `mermaid-diagrams` skill when it is available.
 
 **.mmd files in a DIAGRAMS/ directory** must also use standard flowchart syntax if they need to render via `mmdc` or on GitHub. Files using C4-plugin syntax can only render in tools that bundle the plugin (e.g., Mermaid Live Editor, mmdc with C4 extension config). If you commit `.mmd` files with C4 syntax to a repo, GitHub's file preview will show them as raw text — convert them to standard syntax or render them to PNG first.
 
@@ -100,3 +110,9 @@ A GitHub Community feature request to bundle the C4 mermaid plugin was filed at
 ## Portability
 
 This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.
+
+## When not to use
+
+- Use `mermaid-diagrams` for Mermaid grammar, renderer compatibility, layout, and export troubleshooting that does not require C4 level/model decisions.
+- Use `software-architecture` for architecture drivers, tradeoffs, decisions, and fitness evidence; this skill visualizes those decisions rather than owning them.
+- Use `web-accessibility` for complete WCAG/ARIA conformance work and assistive-technology evidence; this skill contributes diagram-specific accessibility checks and fallbacks.

c4-diagramming/evals/evals.json

@@ -0,0 +1,66 @@
+{
+  "schema_version": 1,
+  "skill_name": "c4-diagramming",
+  "evals": [
+    {
+      "id": "context-view-for-new-maintainer",
+      "prompt": "Create a C4 view for a new maintainer who needs to understand the system boundary and external import dependencies before changing an ingestion path. Keep the view useful in a GitHub README.",
+      "expected_output": "A C4 system-context view with a stated audience and job, consistent abstraction, a clear read order, labeled relationships, a legend or explanation where needed, and a text fallback. It uses GitHub-compatible Mermaid or explains why another format is chosen.",
+      "assertions": [
+        "The audience and reader job are stated before the diagram",
+        "The view stays at system-context abstraction and does not mix container internals",
+        "External dependencies and relationships have meaningful labels",
+        "The output includes a text-only summary or equivalent accessible fallback",
+        "GitHub Mermaid compatibility is addressed without claiming syntax validity proves communication quality"
+      ]
+    },
+    {
+      "id": "container-view-signal-to-noise",
+      "prompt": "Review a proposed container diagram with 28 nodes, several crossed edges, database icons mixed with services, and three colors that indicate criticality. The team wants to use it in an incident handoff.",
+      "expected_output": "A review that identifies the view as overloaded, proposes a smaller incident-oriented container view or split views, preserves C4 level ownership, and replaces color-only criticality with redundant meaning.",
+      "assertions": [
+        "The review names the incident handoff audience and job",
+        "Node and edge density are treated as a signal-to-noise problem rather than completeness",
+        "The proposed revision keeps container-level abstraction consistent",
+        "Criticality is encoded with labels, line or shape differences, or text in addition to color",
+        "The review distinguishes C4 communication review from incident procedure and architecture decision ownership"
+      ]
+    },
+    {
+      "id": "uncertain-target-model",
+      "prompt": "Document a target architecture that is still being validated. Some integrations are confirmed, one data store is inferred from code, and the future event path is only a proposal. Produce a C4 view and review notes.",
+      "expected_output": "A C4 view that marks confirmed, inferred, and proposed information explicitly, avoids false precision, and records evidence and open questions without turning the diagram into an architecture decision record.",
+      "assertions": [
+        "Confirmed, inferred, and proposed claims are visibly distinguished without relying on color alone",
+        "The output records the evidence source or uncertainty for the inferred store and proposed event path",
+        "The selected C4 level and scope are stated",
+        "Open questions are separated from asserted relationships",
+        "The output routes consequential architecture decisions to software-architecture or ADR ownership"
+      ]
+    },
+    {
+      "id": "related-view-consistency",
+      "prompt": "Generate system-context, container, and component views for a payments platform. Check that names, boundaries, and relationship meanings remain coherent across views while each view serves a different reader.",
+      "expected_output": "Three linked views with explicit audience/job and read order, stable identities and boundaries, deliberate scope changes, and evidence of rendered review.",
+      "assertions": [
+        "Each view has a distinct audience or question and does not try to answer every question",
+        "Element identities and relationship meanings remain consistent across levels",
+        "Scope omissions are documented instead of implying nonexistent elements",
+        "The component view does not silently redefine a container boundary",
+        "Rendered-output review evidence is recorded for each target surface"
+      ]
+    },
+    {
+      "id": "accessibility-boundary",
+      "prompt": "A product manager asks for an accessible C4 architecture diagram for a roadmap review, including a color-coded legend and a WCAG conformance statement. Explain what to produce and which work must be handed off.",
+      "expected_output": "A diagram communication plan with redundant non-color encoding, labels, reading order, text fallback, and review evidence, plus an explicit handoff to web-accessibility for full conformance and assistive-technology evaluation.",
+      "assertions": [
+        "The roadmap audience and decision job are defined",
+        "The plan requires meaning that survives color loss and zoom",
+        "A textual or tabular equivalent is specified",
+        "The output refuses to claim full WCAG conformance from diagram checks alone",
+        "C4 model decisions remain distinct from accessibility conformance ownership"
+      ]
+    }
+  ]
+}

c4-diagramming/references/technical-diagram-communication.md

@@ -0,0 +1,31 @@
+# C4 Diagram Communication Review
+
+Use this reference after the C4 level and model scope are chosen, and before calling a diagram complete. It improves the communication artifact without changing C4 ownership.
+
+## 1. Audience and job
+
+Write one sentence for the primary reader and the decision or task the view supports. For example: "A new maintainer needs to locate the system boundary and its external dependencies before changing the import path." If different readers need different jobs, produce separate views or a short sequence rather than one overloaded diagram.
+
+## 2. Abstraction and representation
+
+- Keep every element at the selected C4 level unless a deliberate reference to an adjacent level is labeled and explained.
+- Use one vocabulary for people, systems, containers, components, code, stores, and relationships; do not make shape or color carry an undocumented category.
+- Keep boundaries meaningful: a boundary should represent a real ownership or modeling scope, not a decorative grouping.
+- Make relationship direction, interaction purpose, and technology detail comparable across the view. Do not label one edge with a protocol while labeling another with an unresolved business claim.
+- Preserve the same element identity and naming across related C4 views. If a view omits an element, state that it is out of scope rather than implying it does not exist.
+
+## 3. Narrative and visual hierarchy
+
+Give the reader an entry point and an intended read order. Use title, short purpose statement, boundary order, spatial grouping, and relationship emphasis to lead from context to the claim that matters. Keep the primary path visually dominant; demote supporting paths and move implementation detail to a deeper view. A legend explains notation, not the story, so do not use it as a substitute for a caption.
+
+Reduce signal loss by removing relationships that do not support the stated job, splitting dense views, shortening labels, and moving rationale to an ADR or accompanying prose. More nodes and edges are not evidence of completeness.
+
+## 4. Labels, legend, and uncertainty
+
+Use names that a reader can recognize without decoding internal abbreviations. Label relationships with the interaction or dependency the reader needs to understand. Add a legend only for non-obvious shapes, line styles, or categories, and keep it consistent with the diagram. Mark inferred, proposed, stale, or unknown elements and relationships in text or a documented line style; never imply certainty through polished layout.
+
+## 5. Accessibility and review evidence
+
+Meaning must survive grayscale, color-vision differences, zoom, small screens, and a text-only reading path. Pair color with labels, shapes, line styles, or explicit annotations. Provide a concise textual summary or table that names boundaries, elements, relationships, reading order, and uncertainty. Route full WCAG/ARIA and assistive-technology evaluation to `web-accessibility`.
+
+Capture review evidence: audience/job, selected C4 level, source/model validation, rendered-tool and version, viewport or output surface, accessibility fallback, uncertainty register, reviewer, date, and concrete findings or accepted exceptions. Review the rendered result, not only the DSL or Mermaid source. A valid model and valid syntax are necessary but insufficient; a diagram can pass both and still fail its communication job.

llms.txt

@@ -18,7 +18,7 @@
 - [backend-engineering](backend-engineering/SKILL.md): Design and implement backend services and APIs — REST, gRPC, GraphQL, event-driven handlers, transaction boundaries, outbox/inbox delivery, migration coexistence, database access, integration, error handling, and service-level testing. Use for application/domain/infrastructure implementation decisions. Language and framework agnostic. Do not use for frontend, data engineering, platform provisioning, API contract ownership, service decomposition strategy, or cross-system migration planning.
 - [binary-analysis](binary-analysis/SKILL.md): Analyze unknown binary files through a deterministic CLI that wraps Ghidra's static-analysis engine. Use when you need to inspect a PE, ELF, or Mach-O file — triage suspicious binaries, map imported APIs, decompile functions, trace call paths, or produce structured evidence reports. Do not use for runtime analysis (debugging, dynamic tracing, sandbox execution), for modifying or patching binaries, or for binaries you already know everything about. The skill owns planning, hypothesis formation, and evidence synthesis; the CLI owns all deterministic operations.
 - [brand-designer](brand-designer/SKILL.md): Create comprehensive brand identity documentation for any brand. Guides you through documenting strategy, visual identity (logo, color, typography, imagery), voice and tone, application guidelines, governance, and asset inventory. Produces markdown specs, compiled brand books, and brand-compliant images via reference-image-aware generation. Use when you need to capture a brand's identity in structured, durable form — for vault storage, agency handoff, or press kit distribution.
-- [c4-diagramming](c4-diagramming/SKILL.md): Create C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need clear system context, container, component, or code-level views.
+- [c4-diagramming](c4-diagramming/SKILL.md): Create and review C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need a communication-ready system context, container, component, or code-level view, including audience, narrative, hierarchy, labels, legends, accessibility, and uncertainty. Do not use for Mermaid syntax/rendering work without C4 modeling, architecture decisions, or full accessibility conformance reviews.
 - [capacity-and-cost-engineering](capacity-and-cost-engineering/SKILL.md): Model technical capacity, unit cost, and budget constraints connected to demand, performance, and reliability decisions. Use when projecting capacity from growth forecasts, sizing for peak events, designing cost-aware scaling policies, defining budget thresholds or quota/rate-limit enforcement, running or planning load/soak tests as capacity evidence, resolving SLO-cost tradeoffs, or modeling multi-tenant demand distributions, hot-tenant skew, pooled or siloed headroom, fairness evidence, and tenant-variable unit cost. Do NOT use for financial P&L statements, fundraising scenarios, or SaaS metrics (route to financial-modeling); for infrastructure implementation or cloud-resource provisioning (route to platform-engineering); or for generic cloud-cost tips and universal utilization targets — this skill does not prescribe fixed savings rates or one-size-fits-all thresholds.
 - [chief-of-staff-methodology](chief-of-staff-methodology/SKILL.md): Prepare accountable executive decisions, information triage, briefing, calendar choices, organizational sensing, and institutional memory without assuming authority or monitoring people. Use when a chief of staff or CoS, executive office, gatekeeping, decision memo, executive briefing, board materials, organizational sensing, team health, institutional memory, calendar triage, meeting audit, strategic time, or attention allocation is requested.
 - [cli-builder](cli-builder/SKILL.md): Build or refactor CLI tools designed for AI agent consumption: non-interactive, flag-driven, idempotent, with --json output and --dry-run preview. Use when creating a new script the agent will call, adding agent-friendly flags to an existing tool, or debugging why an agent keeps failing to use your CLI.
@@ -75,7 +75,7 @@
 - [linear](linear/SKILL.md): Manage Linear teams, projects, cycles, issues, comments, workflow state, and documents from a terminal through Linear's public GraphQL API. Use when a user asks to list, search, inspect, create, update, move, or comment on Linear work, or to find Linear documents. Do not use to embed a live agent inside Linear or to build an MCP integration.
 - [llama-cpp](llama-cpp/SKILL.md): Operate, configure, benchmark, and troubleshoot llama.cpp across CPU, Metal, CUDA, HIP/ROCm, Vulkan, SYCL, and hybrid or multi-GPU systems. Use when installing or building llama.cpp, selecting or inspecting GGUF models, running llama-cli, serving an OpenAI-compatible API with llama-server, tuning memory and performance, or diagnosing backend, context, template, and API failures. Do not use for model training or fine-tuning, general inference-framework selection, llama-cpp-python or other bindings, LlamaIndex, Ollama, or LM Studio operation.
 - [llamaindex](llamaindex/SKILL.md): Expert skill for building LLM applications with the LlamaIndex framework — RAG pipelines, multi-agent orchestration, event-driven workflows, knowledge graph construction, production deployment, and evaluation. Use when working with LlamaIndex or comparing RAG and agent orchestration frameworks.
-- [mermaid-diagrams](mermaid-diagrams/SKILL.md): Author, render, and troubleshoot Mermaid diagrams for documentation, architecture, processes, and technical communication. Use when a text-based diagram needs to stay versionable.
+- [mermaid-diagrams](mermaid-diagrams/SKILL.md): Author, render, troubleshoot, and review Mermaid diagrams for documentation, architecture, processes, and technical communication. Use when a versionable diagram must communicate a defined audience job across a real renderer, including narrative, hierarchy, labels, legends, accessibility fallback, and uncertainty. Do not use for C4 level/model ownership, architecture decisions, or full accessibility conformance.
 - [meshcore-packet-capture](meshcore-packet-capture/SKILL.md): Capture MeshCore Companion packets via BLE, serial, or TCP.
 - [migration-engineering](migration-engineering/SKILL.md): Plan and execute safe cross-system migrations, including service extraction from monoliths. Use when moving data, schemas, interfaces, infrastructure, or service ownership through compatibility windows, dual-running, reconciliation, cutover, recovery, or deprecation. Do not use for deciding whether decomposition is justified, designing a target architecture, or implementing one named technology; route those to the relevant architecture or specialist skill.
 - [ml-engineering](ml-engineering/SKILL.md): Plan and execute production ML engineering work — model training and fine-tuning (LoRA/QLoRA), evaluation and eval-set design, quantization decisions, inference deployment, and regression triage, grounded in practical engineering patterns for production ML systems. Do not use for statistical modeling and experimental design (that's the data scientist) or for operating a specific inference engine (that's a tool skill such as llama-cpp or vllm).

mermaid-diagrams/README.md

@@ -13,12 +13,12 @@ Use it when the work needs a repeatable process and an inspectable result. It is
 | Path | What it provides |
 |---|---|
 | `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. |
-| `references/` | Reference material: `c4-mermaid.md`, `c4-to-flowchart.md`, `flowchart.md`, `mmdc-spacing-config.md`, `pdf-rendering-pipeline.md`, `portrait-layout.md`, `sequence.md` |
+| `references/` | Reference material for Mermaid diagram types, C4 compatibility, rendering, layout, and communication review, including `diagram-communication.md`. |
 | `scripts/` | Scripts: `validate-mermaid.sh` |
 
 ## Quick Start
 
-Choose the diagram type in `SKILL.md`, author the smallest useful diagram, and render it with the documented verification path.
+Choose the diagram type in `SKILL.md`, state the audience's job, author the smallest useful diagram, and render and review it on the target surface.
 
 Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below.
 
@@ -26,6 +26,7 @@ Install or expose this directory using your agent's standard Agent Skills loadin
 
 - Author, render, and troubleshoot Mermaid diagrams for documentation, architecture, processes, and technical communication. Use when a text-based diagram needs to stay versionable.
 - Requests involving the method, deliverables, or review process described in `SKILL.md`.
+- Requests to improve diagram narrative, hierarchy, labels, legends, uncertainty, accessible fallback, or signal-to-noise after syntax is valid.
 - Work where a reusable template or reference from this skill would reduce avoidable mistakes.
 
 ## Requirements

mermaid-diagrams/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mermaid-diagrams
-description: Author, render, and troubleshoot Mermaid diagrams for documentation, architecture, processes, and technical communication. Use when a text-based diagram needs to stay versionable.
+description: Author, render, troubleshoot, and review Mermaid diagrams for documentation, architecture, processes, and technical communication. Use when a versionable diagram must communicate a defined audience job across a real renderer, including narrative, hierarchy, labels, legends, accessibility fallback, and uncertainty. Do not use for C4 level/model ownership, architecture decisions, or full accessibility conformance.
 license: MIT
 compatibility: Mermaid rendering requires a compatible renderer. The optional CLI examples use Mermaid CLI and its documented Node.js runtime.
 metadata:
@@ -16,11 +16,12 @@ Portable Mermaid.js diagramming for architectural documentation. Not tied to any
 ## When to Use
 
 Load this skill when:
-- Creating C4 structural views (use Structurizr DSL for production; flowchart workarounds for inline markdown)
+- Rendering C4 flowchart approximations after the C4 level and model have been chosen; use `c4-diagramming` for C4 modeling decisions
 - Producing sequence diagrams for interaction flows
 - Designing flowcharts for process documentation
 - Building state/class/ER diagrams for specification
 - Generating any diagram that needs to render in both agent-facing and human-facing contexts
+- Reviewing whether a structurally valid Mermaid diagram is the right communication artifact for its audience and output surface
 
 Do NOT load when:
 - A plain text outline communicates the relationship more clearly than a diagram.
@@ -42,13 +43,19 @@ Do NOT leave ```mermaid code blocks in markdown that will go through Pandoc. The
 
 See `references/pdf-rendering-pipeline.md` for the full pipeline with Puppeteer setup, SVG styling fixes, and QA checklist.
 
+## Communication Review
+
+Before authoring, state the audience, reader job, target surface, and intended read order. Choose the smallest diagram type and scope that supports that job. Keep abstraction, node shapes, edge semantics, labels, boundary treatment, and visual hierarchy consistent. Syntax validation and a successful render are necessary but not sufficient: a diagram can be valid Mermaid and still be the wrong communication artifact because it is too dense, hides the primary path, mixes representational conventions, or leaves the reader to infer uncertainty.
+
+Load `references/diagram-communication.md` when creating, revising, or reviewing a diagram for people rather than only testing grammar. Use its review record for narrative, signal-to-noise, labels and legends, color-independent meaning, accessibility fallback, uncertainty, and rendered review evidence. C4 level/model ownership stays with `c4-diagramming`; architecture decisions stay with `software-architecture`; full accessibility conformance stays with `web-accessibility`.
+
 ## Supported Diagram Types
 
 | Type | Use Case | File |
 |------|----------|------|
 | Flowchart | Process flows, C4 workarounds, decision trees | `references/flowchart.md` |
 | Sequence | Interaction protocols and API calls | `references/sequence.md` |
-| C4 | Architecture context and container views | `references/c4-mermaid.md` |
+| C4 rendering | Flowchart approximation of a C4 view already chosen with `c4-diagramming` | `references/c4-mermaid.md` |
 | Portrait Layout | PDF/print-oriented diagramming — TD over LR, page breaks, full-page diagrams | `references/portrait-layout.md` |
 | PDF Rendering Pipeline | Full pipeline from .mmd → SVG → HTML → PDF, with QA checklist | `references/pdf-rendering-pipeline.md` |
 | mmdc Spacing Config | Config for controlling diagram density and preventing label overlap | `references/mmdc-spacing-config.md` |
@@ -176,3 +183,9 @@ Key theme variables:
 ## Portability
 
 This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.
+
+## When not to use
+
+- Use `c4-diagramming` when the task is to choose or maintain C4 system-context, container, component, or code-level models.
+- Use `software-architecture` for architecture drivers, tradeoffs, decisions, and fitness evidence rather than diagram syntax or rendering.
+- Use `web-accessibility` for complete WCAG/ARIA conformance and assistive-technology evaluation; this skill supplies diagram-specific checks and fallbacks only.

mermaid-diagrams/evals/evals.json

@@ -0,0 +1,66 @@
+{
+  "schema_version": 1,
+  "skill_name": "mermaid-diagrams",
+  "evals": [
+    {
+      "id": "github-flowchart-review",
+      "prompt": "Create a Mermaid architecture diagram for a GitHub README showing a user, the application, and two external services. Make it understandable to a new contributor and verify that the chosen syntax renders on GitHub.",
+      "expected_output": "A GitHub-compatible flowchart with a stated audience/job, clear entry point and read order, labeled relationships, consistent representations, and a text fallback or summary.",
+      "assertions": [
+        "The output chooses standard GitHub-compatible Mermaid syntax rather than unsupported native C4 syntax",
+        "The audience and contributor question are stated",
+        "Nodes and relationships use consistent labels and meanings",
+        "The diagram has an intentional read order and avoids unnecessary detail",
+        "A text summary or equivalent accessible fallback is provided"
+      ]
+    },
+    {
+      "id": "pdf-rendering-and-communication",
+      "prompt": "Turn a 16-node process flow into a PDF-ready Mermaid artifact. The current render is too wide, labels overlap, and the proposed status colors are the only distinction between states.",
+      "expected_output": "A plan that splits or restructures the flow, uses the PDF rendering path and portrait constraints, resolves label overlap, and adds non-color status meaning while documenting the audience and review evidence.",
+      "assertions": [
+        "The output treats width, density, and overlap as communication defects rather than only renderer defects",
+        "The PDF path pre-renders Mermaid and checks the rendered result",
+        "The diagram is split or otherwise kept within a readable portrait scope",
+        "Status meaning is redundant with labels, shapes, or line styles rather than color alone",
+        "Target surface, renderer/version, and review evidence are recorded"
+      ]
+    },
+    {
+      "id": "sequence-read-order",
+      "prompt": "Review a sequence diagram of an order flow with seven participants, retries, a timeout branch, and a reconciliation step. It is intended for support engineers diagnosing delayed orders.",
+      "expected_output": "A support-oriented sequence diagram review that preserves temporal order, makes retry/timeout/reconciliation behavior legible, and splits or scopes the diagram if seven participants create noise.",
+      "assertions": [
+        "The support audience and diagnostic job are stated",
+        "Temporal read order and timeout/reconciliation paths are explicit",
+        "Participant or message density is reduced or split when it obscures the diagnostic path",
+        "Retry and failure notation has a documented, consistent meaning",
+        "The review distinguishes communication choices from backend behavior ownership"
+      ]
+    },
+    {
+      "id": "uncertainty-and-legend",
+      "prompt": "A Mermaid flowchart documents a proposed migration. Solid arrows are confirmed, dotted arrows are inferred, and dashed arrows are future work, but the legend is incomplete and the render uses three colors with no labels.",
+      "expected_output": "A review that completes or redesigns the legend, makes uncertainty understandable without color, preserves consistent line semantics, and identifies the evidence needed for inferred relationships.",
+      "assertions": [
+        "Confirmed, inferred, and future relationships are explicitly labeled or otherwise understandable without color",
+        "The legend matches the actual line styles and does not substitute for a narrative",
+        "The output identifies evidence gaps for inferred relationships",
+        "Color is treated as supplementary rather than the sole semantic channel",
+        "The output avoids claiming that a valid render proves the migration plan is correct"
+      ]
+    },
+    {
+      "id": "c4-and-accessibility-routing",
+      "prompt": "The team asks for a Mermaid C4 container diagram, a system architecture decision, and a WCAG conformance statement for the published page. Explain the diagram work and handoffs without absorbing neighboring owners.",
+      "expected_output": "A scoped response that routes C4 model level decisions to c4-diagramming, architecture decisions to software-architecture, and complete accessibility conformance to web-accessibility while retaining Mermaid authoring/rendering and diagram communication review here.",
+      "assertions": [
+        "C4 level and model ownership are routed to c4-diagramming",
+        "Architecture drivers and decisions are routed to software-architecture",
+        "Full WCAG/ARIA and assistive-technology evidence are routed to web-accessibility",
+        "Mermaid syntax, renderer compatibility, target-surface rendering, and communication review remain in scope",
+        "The response does not store this boundary test as a trigger-only claim or pretend one validator proves all three outcomes"
+      ]
+    }
+  ]
+}

mermaid-diagrams/references/c4-mermaid.md

@@ -1,38 +1,12 @@
-# C4 Model with Mermaid
+# Rendering a Chosen C4 View with Mermaid
 
-Mermaid does NOT have stable native C4 syntax. `C4Context` and `C4Container` are experimental and unreliable. For production C4 diagrams, use **Structurizr DSL**. For inline markdown where Structurizr isn't available, use the flowchart workaround below.
+This reference does not choose the C4 level, model elements, boundaries, or relationships. Make those decisions with `c4-diagramming`, then use this reference to render the resulting view on a Mermaid-compatible surface.
 
-## Option 1: Structurizr DSL (Recommended)
+Mermaid does not have stable native C4 syntax. `C4Context` and `C4Container` are experimental and unreliable across common renderers. For a durable C4 model and Structurizr workflow, return to `c4-diagramming`. For inline Markdown where only standard Mermaid renders, use the flowchart approximation below.
 
-Structurizr is the canonical C4 tool. The DSL compiles to Mermaid, PlantUML, or Structurizr's own diagram format.
+## Flowchart Workaround for Inline Markdown
 
-```dsl
+Use Mermaid flowchart subgraphs and styling to represent only the elements and relationships in the already-chosen C4 view. Do not infer a level, add architecture content, or redefine a boundary while converting it.
-workspace {
-  model {
-    user = person "User" "A user of the system"
-    system = softwareSystem "Research Service" "A web-retrieval service"
-    user -> system "Uses"
-  }
-  views {
-    systemContext "SystemContext" {
-      include *
-      autoLayout
-    }
-  }
-}
-```
-
-Render with:
-```bash
-# Via Structurizr CLI
-java -jar structurizr-cli.jar render -w workspace.dsl -f mermaid -o output/
-
-# Or use the structurizr-site-generatr for full documentation site
-```
-
-## Option 2: Flowchart Workaround (For Inline Markdown)
-
-Use Mermaid flowchart subgraphs with styling to approximate C4 views. The pattern uses two boxes per element (one for the system/person, one for a description).
 
 ### System Context (L1)
 
@@ -101,4 +75,4 @@ flowchart TB
 - No native C4 shapes (person, system, container, database) — must approximate with subgraphs
 - No automatic layout — manual positioning via subgraph nesting
 - No relationship descriptions on edges (can add via edge labels)
-- Structurizr DSL is the right tool for C4. Use Mermaid flowchart workarounds only when Structurizr is unavailable.
+- Use `c4-diagramming` for C4 modeling and Structurizr decisions. Use Mermaid flowchart approximations only to render an already-chosen view when the target surface requires standard Mermaid.

mermaid-diagrams/references/diagram-communication.md

@@ -0,0 +1,25 @@
+# Mermaid Diagram Communication Review
+
+Use this reference after selecting the Mermaid diagram type and before delivery. It supplements syntax and rendering checks with a review of the artifact's human job.
+
+## Audience, job, and narrative
+
+Write the primary audience, the question they need answered, and the target surface: README, issue, wiki, PDF, mobile screen, or another renderer. Put a short purpose statement before the diagram. Arrange nodes and edges so the intended entry point and read order are apparent; use direction, grouping, captions, and a dominant path intentionally. If two audiences need different levels of detail, split the diagram rather than making one canvas serve both.
+
+## Consistent representation
+
+- Use one abstraction level and one meaning for each shape, line style, arrow direction, and boundary.
+- Keep labels parallel: comparable nodes should expose comparable facts, and comparable edges should describe comparable relationships.
+- Use subgraphs for real scopes or meaningful groups, not as decoration. Keep related views consistent in names and boundaries.
+- Treat layout configuration as communication design. Split dense diagrams, shorten labels with deliberate line breaks, and tune spacing only after removing unnecessary signal.
+- Add a legend for non-obvious notation, and make it agree with the actual diagram. A legend cannot repair a missing narrative.
+
+## Signal, uncertainty, and color
+
+Prefer the smallest diagram that answers the stated question. Remove nodes and edges that do not support it, or move them to a linked detail view. Mark proposed, inferred, stale, or unknown relationships in text, labels, or documented line styles. Never let a polished render imply evidence that the source does not have. Pair color with text, shape, line style, or position so meaning remains available in grayscale and for readers with color-vision differences.
+
+## Accessibility and review evidence
+
+Provide a text-only summary or table that names the entry point, nodes, boundaries, relationships, read order, and uncertainty. Use readable labels, sufficient contrast, scalable output, and a target-surface check; do not rely on emoji or color as the only identifier. Route complete WCAG/ARIA and assistive-technology conformance work to `web-accessibility`.
+
+Record the audience/job, diagram type, renderer and version, target surface and viewport, source validation result, rendered review result, text fallback, uncertainty notes, reviewer, date, and concrete findings or accepted exceptions. Review the rendered output at the size readers will encounter. Mermaid syntax and rendering can both pass while the communication artifact still fails its job.

references/skill-triggers.md

@@ -91,9 +91,9 @@ Each skill's `description` field is the canonical routing contract. This conveni
 | "technical-documentation", "technical documentation" | [technical-documentation](../technical-documentation/SKILL.md) |
 | "secure software engineering", "build securely", "secure by design", "security requirements", "security acceptance criteria", "threat model this design", "secure code review", "secure defaults", "authorization design", "multi-tenant isolation", "tenant trust boundary", "control-plane security", "application-plane security", "tenant identity propagation", "support impersonation security", "tenant backup security", "tenant export security", "tenant deletion security", "noisy neighbor security", "resource exhaustion tenant", "release evidence", "SBOM", "software supply chain", "AI security", "LLM security", "prompt injection", "tool authorization", "RAG security" | [secure-software-engineering](../secure-software-engineering/SKILL.md) |
 | "security-audit-methodology", "security audit methodology" | [security-audit-methodology](../security-audit-methodology/SKILL.md) |
-| "mermaid-diagrams", "mermaid diagrams" | [mermaid-diagrams](../mermaid-diagrams/SKILL.md) |
+| "mermaid-diagrams", "mermaid diagrams", "diagram narrative", "diagram hierarchy", "diagram legend", "diagram accessibility fallback", "Mermaid communication review" | [mermaid-diagrams](../mermaid-diagrams/SKILL.md) |
 | "adr-authoring", "adr authoring", "architecture decision record", "fitness function", "decision confirmation" | [adr-authoring](../adr-authoring/SKILL.md) |
-| "c4-diagramming", "c4 diagramming" | [c4-diagramming](../c4-diagramming/SKILL.md) |
+| "c4-diagramming", "c4 diagramming", "C4 communication review", "C4 audience", "C4 read order", "C4 abstraction consistency" | [c4-diagramming](../c4-diagramming/SKILL.md) |
 | "capacity engineering", "cost engineering", "capacity model", "capacity planning", "unit cost", "cost per request", "cost per user", "budget threshold", "spending alert", "spending cap", "rate limit enforcement", "quota management", "load test plan", "soak test plan", "capacity projection", "growth forecast capacity", "peak sizing", "degraded capacity", "SLO cost tradeoff", "cost attribution", "cost anomaly review", "cost-aware architecture", "cost-performance tradeoff", "tenant capacity", "tenant demand distribution", "hot tenant capacity", "partition skew capacity", "pooled headroom", "siloed headroom", "tenant fairness evidence", "tenant variable cost" | [capacity-and-cost-engineering](../capacity-and-cost-engineering/SKILL.md) |
 | "technology-radar", "technology radar", "technology portfolio governance", "proportional technology governance", "technology advice process", "federated technology decision", "technology standards exception", "technology standards" | [technology-radar](../technology-radar/SKILL.md) |
 | "strategy", "strategic planning", "OKRs", "strategic narrative", "Five Forces", "Blue Ocean", "competitive positioning", "moat", "Ansoff", "Three Horizons", "market entry", "capital allocation", "M&A evaluation", "BCG Matrix", "portfolio management" | [strategy-frameworks](../strategy-frameworks/SKILL.md) |