design-doc-mermaid

# Mermaid Architect - Hierarchical Diagram and Documentation Skill Mermaid diagram and documentation system with specialized guides and code-to-diagram capabilities. ## Table of Contents - [Decision Tree](#decision-tree) - [Available Guides and Resources](#available-guides-and-resources) - [Usage Patterns](#usage-patterns) - [Resilient Workflow](#resilient-workflow) - [Unicode Semantic Symbols](#unicode-semantic-symbols) - [Python Utilities](#python-utilities) - [Decision Tree Examples](#decision-tree-examples) - [High-Contrast Styling](#high-contrast-styling) - [File Organization](#file-organization) - [Workflow Summary](#workflow-summary) - [When to Use What](#when-to-use-what) - [Best Practices](#best-practices) - [Learning Path](#learning-path) ## Decision Tree **How this skill works:** 1. **User makes a request** → Skill analyzes intent 2. **Skill determines diagram/document type** → Loads appropriate guide(s) 3. **Value Gate (MANDATORY)** → Before generating, pass the reverse-conversion test 4. **AI reads specialized guide** → Generates diagram/document using templates 5. **Result delivered** → With validation and export options ### Value Gate: reverse-conversion test (run before drawing) A diagram must let the reader grasp the **structure** (relations, flow, hierarchy, branching) at a glance without reading prose. A diagram that merely re-packages sentences into boxes is noise, not visualization. See `docs/policy/documentation-policy.md` (「図にする前に『逆変換テスト』を通す」). **Before generating any diagram, ask: "If I convert this diagram back into a bullet list, is any information lost?"** - **Straight line (A→B→C) with no branch / merge / loop / parallelism**: No value → use a bullet list, not a diagram - **Nodes convert back to bullets with zero information loss**: No value → use a table or bullet list - **Just a 1-to-1 enumeration**: No value → use a table Only draw when the content needs 2D placement — branching, merging, loops, parallelism, many-to-many, hierarchy, or state transitions. Diagram count is never a goal in itself. ### Type Gate: choose by shape, not by wording (run after the value gate) Once you have decided to draw, **read `references/diagram-type-selection.md` and pick the type from the shape of the information** — not from the words the user used. "Show me the workflow" does not mean `flowchart`: if states change, it is `stateDiagram-v2`; if several actors exchange messages, it is `sequenceDiagram`; if work sits in status lanes, it is `kanban`. `flowchart` / `graph` is the **last resort**, not the default. It can express almost anything, and that is exactly why it is chosen too often — being able to express something is not the same as being suited to it. - **Pick from the shape**: Read `references/diagram-type-selection.md` and take the first matching row - **flowchart needs justification**: Choose it only when every other row fails. Then state in one line why no other type fits - **Cannot justify it?**: Choose again — the inability to explain means the shape was never checked - **A matching row is not a licence**: Some types have narrow limits (`architecture-beta` cannot label edges at all). Check the row's conditions before committing GitHub renders all 26 Mermaid diagram types (verified by rendering probe), so availability is never a reason to fall back to `flowchart`. Expressiveness is a separate question: when the chosen type cannot carry the information, `graph` with a stated reason is the correct answer, not a failure. **User Intent Analysis:** ```mermaid flowchart TD Start([User Request]) --> Analyze{Analyze Intent} Analyze -->|"a diagram is warranted"| TypeGate[Read Type Selection Table<br/>references/diagram-type-selection.md] TypeGate --> Shape{Match the shape<br/>of the information} Shape -->|"time-ordered exchange between actors"| Sequence[Load Sequence Diagram Guide<br/>references/guides/diagrams/sequence-diagrams.md] Shape -->|"infrastructure, deployment, cloud"| Deploy[Load Deployment Diagram Guide<br/>references/guides/diagrams/deployment-diagrams.md] Shape -->|"system components and boundaries"| Arch[Load Architecture Guide<br/>references/guides/diagrams/architecture-diagrams.md] Shape -->|"state / entity / hierarchy / quantity / set"| Catalog[Load Full Type Catalog<br/>references/mermaid-diagram-guide.md] Shape -->|"branching with no better fit"| Activity[Load Activity Diagram Guide<br/>references/guides/diagrams/activity-diagrams.md<br/>state why no other type fits] Analyze -->|"code to diagram"| CodeToDiag[Load Code-to-Diagram Guide<br/>references/guides/code-to-diagram/ + examples/] Analyze -->|"design document, full docs"| DesignDoc[Load Design Document Template<br/>assets/*-design-template.md] Analyze -->|"unicode symbols, icons"| Unicode[Load Unicode Symbols Guide<br/>references/guides/unicode-symbols/guide.md] Analyze -->|"extract, validate, convert"| Scripts[Use Python Scripts<br/>scripts/extract_mermaid.py<br/>scripts/mermaid_to_image.py] Activity --> Generate[Generate Diagram] Deploy --> Generate Arch --> Generate Sequence --> Generate CodeToDiag --> Generate DesignDoc --> Generate Unicode --> Generate Scripts --> Execute[Execute Script] Generate --> Validate{Validate?} Validate -->|Yes| RunValidation[Run mmdc validation] Validate -->|No| Output RunValidation --> Output[Output Result] Execute --> Output classDef decision fill:#FFD700,stroke:#333,stroke-width:2px,color:black classDef guide fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen classDef action fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue class Analyze,Validate,Shape decision class TypeGate,Catalog,Activity,Deploy,Arch,Sequence,CodeToDiag,DesignDoc,Unicode,Scripts guide class Generate,Execute,RunValidation,Output action ``` ## Available Guides and Resources ### Type Selection (read this first) | Resource | Full Path | What It Provides | | ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | **Type Selection Table** | `references/diagram-type-selection.md` | Shape → diagram type, and how each shape degrades if drawn as a flowchart. **Entry point for every diagram.** | | **Full Type Catalog** | `references/mermaid-diagram-guide.md` | Syntax and worked examples for all 26 diagram types | ### Deep-Dive Guides (`references/guides/diagrams/`) These four cover the most common shapes in depth. They are **not** the full set of options — the catalog above is. Do not settle for one of these four just because it loaded first. | Guide | Full Path | Load When The Shape Is | Examples | | --------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Activity Diagrams | `references/guides/diagrams/activity-diagrams.md` | Workflows, processes, business logic, user flows, decision trees | "Show checkout flow", "Document ETL pipeline", "Create approval workflow" | | Deployment Diagrams | `references/guides/diagrams/deployment-diagrams.md` | Infrastructure, cloud architecture, K8s, serverless, network topology | "Show AWS architecture", "Document GCP deployment", "Create K8s diagram" | | Architecture Diagrams | `references/guides/diagrams/architecture-diagrams.md` | System architecture, component design, high-level structure | "Show system components", "Document microservices", "Architecture overview" | | Sequence Diagrams | `references/guides/diagrams/sequence-diagrams.md` | API interactions, service communication, request/response flows | "Show API call sequence", "Document auth flow", "Service interactions" | ### Code-to-Diagram Guide & Examples | Resource | Full Path | What It Provides | | ---------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Master Guide** | `references/guides/code-to-diagram/README.md` | Complete workflow for analyzing any codebase and extracting diagrams | | **Spring Boot** | `examples/spring-boot/README.md` | Controller→Service→Repository architecture, deployment config, sequence from methods, activity from business logic | | **FastAPI** | `examples/fastapi/README.md` | Python async patterns, Pydantic models, dependency injection, cloud deployment | | **React** | `examples/react/README.md` | Component hierarchy, state management, data flow, build pipeline | | **Python ETL** | `examples/python-etl/README.md` | Data pipeline, transformation steps, error handling, scheduling | | **Node/Express** | `examples/node-webapp/README.md` | Middleware chain, route handlers, async patterns, deployment | | **Java Web App** | `examples/java-webapp/README.md` | Traditional MVC, servlet containers, WAR deployment | ### Design Document Templates | Template | Full Path | Use For | Load When | | ------------------- | ---------------------------------------- | ------------------------ | --------------------------------------------------- | | Architecture Design | `assets/architecture-design-template.md` | System-wide architecture | "Create architecture doc", "Document system design" | | API Design | `assets/api-design-template.md` | API specifications | "API design doc", "Document REST API" | | Feature Design | `assets/feature-design-template.md` | Feature planning | "Feature design", "Plan new feature" | | Database Design | `assets/database-design-template.md` | Database schema | "Database design", "Document schema" | | System Design | `assets/system-design-template.md` | Complete system | "System design doc", "Full system documentation" | ### Unicode Symbols Guide **Full Path:** `references/guides/unicode-symbols/guide.md` **Load when user mentions:** "unicode symbols", "emoji in diagrams", "semantic icons", "add symbols" **Quick Reference:** - 📦 Infrastructure: ☁️ 🌐 🔌 📡 🗄️ - ⚙️ Compute: ⚙️ ⚡ 🔄 ♻️ 🚀 💨 - 💾 Data: 💾 📦 📊 📈 🗃️ 🧊 - 📨 Messaging: 📨 📬 📤 📥 🐰 📢 - 🔐 Security: 🔐 🔑 🛡️ 🚪 👤 🎫 - 📝 Monitoring: 📝 📊 🚨 ⚠️ ✅ ❌ ### Python Scripts (`scripts/`) | Script | Use For | Load When |