skills/claude-scientific-skills
1
0
Fork 0
mirror of https://github.com/K-Dense-AI/claude-scientific-skills.git synced 2026-03-27 07:09:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(references): port style guides, 24 diagram guides, and 9 templates from opencode

Browse Source 
All content ported from borealBytes/opencode under Apache-2.0 license with
attribution headers prepended to each file.

- references/markdown_style_guide.md (~733 lines): full markdown formatting,
  citation, collapsible sections, emoji, Mermaid integration, and template
  selection guide
- references/mermaid_style_guide.md (~458 lines): full Mermaid standards —
  emoji set, classDef color palette, accessibility (accTitle/accDescr),
  theme neutrality (no %%{init}), and diagram type selection table
- references/diagrams/ (24 files): per-type exemplars, tips, and templates
  for all Mermaid diagram types
- templates/ (9 files): PR, issue, kanban, ADR, presentation, how-to,
  status report, research paper, project docs

Source: https://github.com/borealBytes/opencode
This commit is contained in:
borealBytes
2026-02-19 18:25:20 -05:00
parent b376b40f59
commit 02e19e3df9
35 changed files with 6687 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
scientific-skills/markdown-mermaid-writing/references/diagrams/architecture.md Normal file
View File

@@ -0,0 +1,108 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Architecture Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `architecture-beta`
**Best for:** Cloud infrastructure, service topology, deployment architecture, network layout
**When NOT to use:** Logical system boundaries (use [C4](c4.md)), component layout without cloud semantics (use [Block](block.md))
> ⚠️ **Accessibility:** Architecture diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Architecture diagram showing a cloud-hosted web application with a load balancer, API server, database, and cache deployed within a VPC:_
```mermaid
architecture-beta
group cloud(cloud)[AWS Cloud]
group vpc(cloud)[VPC] in cloud
service lb(internet)[Load Balancer] in vpc
service api(server)[API Server] in vpc
service db(database)[PostgreSQL] in vpc
service cache(disk)[Redis Cache] in vpc
lb:R --> L:api
api:R --> L:db
api:B --> T:cache
```
---
## Tips
- Use `group` for logical boundaries (VPC, region, cluster, availability zone)
- Use `service` for individual components
- Direction annotations on connections: `:L` (left), `:R` (right), `:T` (top), `:B` (bottom)
- Built-in icon types: `cloud`, `server`, `database`, `internet`, `disk`
- Nest groups with `in parent_group`
- **Labels must be plain text** — no emoji and no hyphens in `[]` labels (parser treats `-` as an edge operator)
- Use `-->` for directional arrows, `--` for undirected edges
- Keep to **6–8 services** per diagram
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of the infrastructure topology and key components:_
```mermaid
architecture-beta
group region(cloud)[Cloud Region]
service frontend(internet)[Web Frontend] in region
service backend(server)[API Server] in region
service datastore(database)[Database] in region
frontend:R --> L:backend
backend:R --> L:datastore
```
---
## Complex Example
_Multi-region cloud deployment with 3 nested groups (2 regional clusters + shared services) showing 9 services, cross-region database replication, CDN distribution, and centralized monitoring. Demonstrates how nested `group` + `in` syntax creates clear infrastructure boundaries:_
```mermaid
architecture-beta
group cloud(cloud)[AWS Platform]
group east(cloud)[US East Region] in cloud
service lb_east(internet)[Load Balancer East] in east
service app_east(server)[App Server East] in east
service db_primary(database)[Primary Database] in east
group west(cloud)[US West Region] in cloud
service lb_west(internet)[Load Balancer West] in west
service app_west(server)[App Server West] in west
service db_replica(database)[Replica Database] in west
group shared(cloud)[Shared Services] in cloud
service cdn(internet)[CDN Edge] in shared
service monitor(server)[Monitoring] in shared
service queue(server)[Message Queue] in shared
cdn:B --> T:lb_east
cdn:B --> T:lb_west
lb_east:R --> L:app_east
lb_west:R --> L:app_west
app_east:B --> T:db_primary
app_west:B --> T:db_replica
db_primary:R --> L:db_replica
app_east:R --> L:queue
app_west:R --> L:queue
monitor:B --> T:app_east
```
### Why this works
- **Nested groups mirror real infrastructure** — cloud > region > services is exactly how teams think about multi-region deployments. The nesting creates clear blast radius boundaries.
- **Plain text labels only** — architecture diagrams parse-fail with emoji in `[]` labels. All visual distinction comes from the group nesting and icon types (`internet`, `server`, `database`).
- **Directional annotations prevent overlap** — `:B --> T:` (bottom-to-top), `:R --> L:` (right-to-left) control where edges connect. Without these, Mermaid stacks edges on top of each other.
- **Cross-region replication is explicit** — the `db_primary:R --> L:db_replica` edge is the most important infrastructure detail and reads clearly as a horizontal connection between regions.

177
scientific-skills/markdown-mermaid-writing/references/diagrams/block.md Normal file
View File

@@ -0,0 +1,177 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Block Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `block-beta`
**Best for:** System block composition, layered architectures, component topology where spatial layout matters
**When NOT to use:** Process flows (use [Flowchart](flowchart.md)), infrastructure with cloud icons (use [Architecture](architecture.md))
> ⚠️ **Accessibility:** Block diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Block diagram showing a three-tier web application architecture from client-facing interfaces through application services to data storage, with emoji labels indicating component types:_
```mermaid
block-beta
columns 3
block:client:3
columns 3
browser["🌐 Browser"]
mobile["📱 Mobile App"]
cli["⌨️ CLI Tool"]
end
space:3
block:app:3
columns 3
api["🖥️ API Server"]
worker["⚙️ Worker"]
cache["⚡ Redis Cache"]
end
space:3
block:data:3
columns 2
db[("💾 PostgreSQL")]
storage["📦 Object Storage"]
end
browser --> api
mobile --> api
cli --> api
api --> worker
api --> cache
worker --> db
api --> db
worker --> storage
```
---
## Tips
- Use `columns N` to control the layout grid
- Use `space:N` for empty cells (alignment/spacing)
- Nest `block:name:span { ... }` for grouped sections
- Connect blocks with `-->` arrows
- Use **emoji in labels** `["🔧 Component"]` for visual distinction
- Use cylinder `("text")` syntax for databases within blocks
- Keep to **3–4 rows** with **3–4 columns** for readability
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of the system layers and how components connect:_
```mermaid
block-beta
columns 3
block:layer1:3
columns 3
comp_a["📋 Component A"]
comp_b["⚙️ Component B"]
comp_c["📦 Component C"]
end
space:3
block:layer2:3
columns 2
comp_d["💾 Component D"]
comp_e["🔧 Component E"]
end
comp_a --> comp_d
comp_b --> comp_d
comp_c --> comp_e
```
---
## Complex Example
_Enterprise platform architecture rendered as a 5-tier block diagram with 15 components. Each tier is a block group spanning the full width, with internal columns controlling component layout. Connections show the primary data flow paths between tiers:_
```mermaid
block-beta
columns 4
block:clients:4
columns 4
browser["🌐 Browser"]
mobile["📱 Mobile App"]
partner["🔌 Partner API"]
admin["🔐 Admin Console"]
end
space:4
block:gateway:4
columns 2
apigw["🌐 API **Gateway**"]
auth["🔐 Auth Service"]
end
space:4
block:services:4
columns 4
user_svc["👤 User Service"]
order_svc["📋 Order Service"]
product_svc["📦 Product Service"]
notify_svc["📤 Notification Service"]
end
space:4
block:data:4
columns 3
postgres[("💾 PostgreSQL")]
redis["⚡ Redis Cache"]
elastic["🔍 Elasticsearch"]
end
space:4
block:infra:4
columns 3
mq["📥 Message Queue"]
logs["📊 Log Aggregator"]
metrics["📊 Metrics Store"]
end
browser --> apigw
mobile --> apigw
partner --> apigw
admin --> auth
apigw --> auth
apigw --> user_svc
apigw --> order_svc
apigw --> product_svc
order_svc --> notify_svc
user_svc --> postgres
order_svc --> postgres
product_svc --> elastic
order_svc --> redis
notify_svc --> mq
order_svc --> mq
mq --> logs
```
### Why this works
- **5 tiers read top-to-bottom** like a network diagram — clients, gateway, services, data, infrastructure. Each tier is a block spanning the full width with its own column layout.
- **`space:4` creates visual separation** between tiers without unnecessary lines or borders, keeping the diagram clean and scannable.
- **Cylinder syntax `("text")` for databases** — PostgreSQL renders as a cylinder, instantly recognizable as a data store. Other components use standard rectangles.
- **Connections show real data paths** — not every possible connection, just the primary flows. A fully-connected diagram would be unreadable; this shows the key paths an engineer would trace during debugging.

136
scientific-skills/markdown-mermaid-writing/references/diagrams/c4.md Normal file
View File

@@ -0,0 +1,136 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# C4 Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `C4Context`, `C4Container`, `C4Component`
**Best for:** System architecture at varying zoom levels — context, containers, components
**When NOT to use:** Infrastructure topology (use [Architecture](architecture.md)), runtime sequences (use [Sequence](sequence.md))
---
## Exemplar Diagram — System Context
```mermaid
C4Context
accTitle: Online Store System Context
accDescr: C4 context diagram showing how a customer interacts with the store and its external payment dependency
title Online Store - System Context
Person(customer, "Customer", "Places orders")
System(store, "Online Store", "Catalog and checkout")
System_Ext(payment, "Payment Provider", "Card processing")
Rel(customer, store, "Orders", "HTTPS")
Rel(store, payment, "Pays", "API")
UpdateRelStyle(customer, store, $offsetY="-40", $offsetX="-30")
UpdateRelStyle(store, payment, $offsetY="-40", $offsetX="-30")
```
---
## C4 Zoom Levels
| Level | Keyword | Shows | Audience |
| ------------- | ------------- | --------------------------------------- | --------------- |
| **Context** | `C4Context` | Systems + external actors | Everyone |
| **Container** | `C4Container` | Apps, databases, queues within a system | Technical leads |
| **Component** | `C4Component` | Internal modules within a container | Developers |
## Tips
- Use `Person()` for human actors
- Use `System()` for internal systems, `System_Ext()` for external
- Use `Container()`, `ContainerDb()`, `ContainerQueue()` at the container level
- Label relationships with **verbs** and **protocols**: `"Reads from", "SQL/TLS"`
- Use `Container_Boundary(id, "name") { ... }` to group containers
- **Keep descriptions short** — long text causes label overlaps
- **Limit to 4–5 elements** at the Context level to avoid crowding
- **Avoid emoji in C4 labels** — the C4 renderer handles its own styling
- Use `UpdateRelStyle()` to adjust label positions if overlaps occur
---
## Template
```mermaid
C4Context
accTitle: Your System Context
accDescr: Describe the system boundaries and external interactions
Person(user, "User", "Role description")
System(main_system, "Your System", "What it does")
System_Ext(external, "External Service", "What it provides")
Rel(user, main_system, "Uses", "HTTPS")
Rel(main_system, external, "Calls", "API")
```
---
## Complex Example
A C4 Container diagram for an e-commerce platform with 3 `Container_Boundary` groups, 10 containers, and 2 external systems. Shows how to use boundaries to organize services by layer, with `UpdateRelStyle` offsets preventing label overlaps.
```mermaid
C4Container
accTitle: E-Commerce Platform Container View
accDescr: C4 container diagram showing web and mobile frontends, core backend services, and data stores with external payment and email dependencies
Person(customer, "Customer", "Shops online")
Container_Boundary(frontend, "Frontend") {
Container(spa, "Web App", "React", "Single-page app")
Container(bff, "BFF API", "Node.js", "Backend for frontend")
}
Container_Boundary(services, "Core Services") {
Container(order_svc, "Order Service", "Go", "Order processing")
Container(catalog_svc, "Product Catalog", "Go", "Product data")
Container(user_svc, "User Service", "Go", "Auth and profiles")
}
Container_Boundary(data, "Data Layer") {
ContainerDb(pg, "PostgreSQL", "SQL", "Primary data store")
ContainerDb(redis, "Redis", "Cache", "Session and cache")
ContainerDb(search, "Elasticsearch", "Search", "Product search")
}
System_Ext(payment_gw, "Payment Gateway", "Card processing")
System_Ext(email_svc, "Email Service", "Transactional email")
Rel(customer, spa, "Browses", "HTTPS")
Rel(spa, bff, "Calls", "GraphQL")
Rel(bff, order_svc, "Places orders", "gRPC")
Rel(bff, catalog_svc, "Queries", "gRPC")
Rel(bff, user_svc, "Authenticates", "gRPC")
Rel(order_svc, pg, "Reads/writes", "SQL")
Rel(order_svc, payment_gw, "Charges", "API")
Rel(order_svc, email_svc, "Sends", "SMTP")
Rel(catalog_svc, search, "Indexes", "REST")
Rel(user_svc, redis, "Sessions", "TCP")
Rel(catalog_svc, pg, "Reads", "SQL")
UpdateRelStyle(customer, spa, $offsetY="-40", $offsetX="-50")
UpdateRelStyle(spa, bff, $offsetY="-30", $offsetX="10")
UpdateRelStyle(bff, order_svc, $offsetY="-30", $offsetX="-40")
UpdateRelStyle(bff, catalog_svc, $offsetY="-30", $offsetX="10")
UpdateRelStyle(bff, user_svc, $offsetY="-30", $offsetX="50")
UpdateRelStyle(order_svc, pg, $offsetY="-30", $offsetX="-50")
UpdateRelStyle(order_svc, payment_gw, $offsetY="-30", $offsetX="10")
UpdateRelStyle(order_svc, email_svc, $offsetY="10", $offsetX="10")
UpdateRelStyle(catalog_svc, search, $offsetY="-30", $offsetX="10")
UpdateRelStyle(user_svc, redis, $offsetY="-30", $offsetX="10")
UpdateRelStyle(catalog_svc, pg, $offsetY="10", $offsetX="30")
```
### Why this works
- **Container_Boundary groups map to deployment units** — frontend, core services, and data layer each correspond to real infrastructure boundaries (CDN, Kubernetes namespace, managed databases)
- **Every `Rel` has `UpdateRelStyle`** — C4's auto-layout stacks labels on top of each other by default. Offset every relationship to prevent overlaps, even if it seems fine at first (adding elements later will shift things)
- **Descriptions are kept to 1-3 words** — "Card processing", "Session and cache", "Auth and profiles". Long descriptions are the #1 cause of C4 rendering issues
- **Container types are semantic** — `ContainerDb` for databases gives them the cylinder icon, `Container` for services. The C4 renderer provides its own visual differentiation

246
scientific-skills/markdown-mermaid-writing/references/diagrams/class.md Normal file
View File

@@ -0,0 +1,246 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Class Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `classDiagram`
**Best for:** Object-oriented design, type hierarchies, interface contracts, domain models
**When NOT to use:** Database schemas (use [ER](er.md)), runtime behavior (use [Sequence](sequence.md))
---
## Exemplar Diagram
```mermaid
classDiagram
accTitle: Payment Processing Class Hierarchy
accDescr: Interface and abstract base class with two concrete implementations for credit card and digital wallet payment processing
class PaymentProcessor {
<<interface>>
+processPayment(amount) bool
+refund(transactionId) bool
+getStatus(transactionId) string
}
class BaseProcessor {
<<abstract>>
#apiKey: string
#timeout: int
+validateAmount(amount) bool
#logTransaction(tx) void
}
class CreditCardProcessor {
-gateway: string
+processPayment(amount) bool
+refund(transactionId) bool
-tokenizeCard(card) string
}
class DigitalWalletProcessor {
-provider: string
+processPayment(amount) bool
+refund(transactionId) bool
-initiateHandshake() void
}
PaymentProcessor <|.. BaseProcessor : implements
BaseProcessor <|-- CreditCardProcessor : extends
BaseProcessor <|-- DigitalWalletProcessor : extends
style PaymentProcessor fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
style BaseProcessor fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
style CreditCardProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
style DigitalWalletProcessor fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
```
---
## Tips
- Use `<<interface>>` and `<<abstract>>` stereotypes for clarity
- Show visibility: `+` public, `-` private, `#` protected
- Keep to **4–6 classes** per diagram — split larger hierarchies
- Use `style ClassName fill:...,stroke:...,color:...` for light semantic coloring:
- 🟣 Purple for interfaces/abstractions
- 🔵 Blue for base/abstract classes
- 🟢 Green for concrete implementations
- Relationship arrows:
- `<|--` inheritance (extends)
- `<|..` implementation (implements)
- `*--` composition · `o--` aggregation · `-->` dependency
---
## Template
```mermaid
classDiagram
accTitle: Your Title Here
accDescr: Describe the class hierarchy and the key relationships between types
class InterfaceName {
<<interface>>
+methodOne() ReturnType
+methodTwo(param) ReturnType
}
class ConcreteClass {
-privateField: Type
+methodOne() ReturnType
+methodTwo(param) ReturnType
}
InterfaceName <|.. ConcreteClass : implements
```
---
## Complex Example
An event-driven notification platform with 11 classes organized into 3 `namespace` groups — core orchestration, delivery channels, and data models. Shows interface implementation, composition, and dependency relationships across layers.
```mermaid
classDiagram
accTitle: Event-Driven Notification Platform
accDescr: Multi-namespace class hierarchy for a notification system showing core orchestration, four delivery channel implementations, and supporting data models with composition and dependency relationships
namespace Core {
class NotificationService {
-queue: NotificationQueue
-registry: ChannelRegistry
+dispatch(notification) bool
+scheduleDelivery(notification, time) void
+getDeliveryStatus(id) DeliveryStatus
}
class NotificationQueue {
-pending: List~Notification~
-maxRetries: int
+enqueue(notification) void
+dequeue() Notification
+retry(attempt) bool
}
class ChannelRegistry {
-channels: Map~string, Channel~
+register(name, channel) void
+resolve(type) Channel
+healthCheck() Map~string, bool~
}
}
namespace Channels {
class Channel {
<<interface>>
+send(notification, recipient) DeliveryAttempt
+getStatus(attemptId) DeliveryStatus
+validateRecipient(recipient) bool
}
class EmailChannel {
-smtpHost: string
-templateEngine: TemplateEngine
+send(notification, recipient) DeliveryAttempt
+getStatus(attemptId) DeliveryStatus
+validateRecipient(recipient) bool
}
class SMSChannel {
-provider: string
-rateLimit: int
+send(notification, recipient) DeliveryAttempt
+getStatus(attemptId) DeliveryStatus
+validateRecipient(recipient) bool
}
class PushChannel {
-firebaseKey: string
-apnsKey: string
+send(notification, recipient) DeliveryAttempt
+getStatus(attemptId) DeliveryStatus
+validateRecipient(recipient) bool
}
class WebhookChannel {
-signingSecret: string
-timeout: int
+send(notification, recipient) DeliveryAttempt
+getStatus(attemptId) DeliveryStatus
+validateRecipient(recipient) bool
}
}
namespace Models {
class Notification {
+id: uuid
+channel: string
+subject: string
+body: string
+priority: string
+createdAt: timestamp
}
class Recipient {
+id: uuid
+email: string
+phone: string
+deviceTokens: List~string~
+preferences: Map~string, bool~
}
class DeliveryAttempt {
+id: uuid
+notificationId: uuid
+recipientId: uuid
+status: DeliveryStatus
+attemptNumber: int
+sentAt: timestamp
}
class DeliveryStatus {
<<enumeration>>
QUEUED
SENDING
DELIVERED
FAILED
BOUNCED
}
}
NotificationService *-- NotificationQueue : contains
NotificationService *-- ChannelRegistry : contains
ChannelRegistry --> Channel : resolves
Channel <|.. EmailChannel : implements
Channel <|.. SMSChannel : implements
Channel <|.. PushChannel : implements
Channel <|.. WebhookChannel : implements
Channel ..> Notification : receives
Channel ..> Recipient : delivers to
Channel ..> DeliveryAttempt : produces
DeliveryAttempt --> DeliveryStatus : has
style Channel fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
style DeliveryStatus fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
style NotificationService fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
style NotificationQueue fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
style ChannelRegistry fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
style EmailChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
style SMSChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
style PushChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
style WebhookChannel fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
style Notification fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
style Recipient fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
style DeliveryAttempt fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
```
### Why this works
- **3 namespaces mirror architectural layers** — Core (orchestration), Channels (delivery implementations), Models (data). A developer can scan one namespace without reading the others.
- **Color encodes the role** — purple for interfaces/enums, blue for core services, green for concrete implementations, gray for data models. The pattern is instantly recognizable.
- **Relationship types are deliberate** — composition (`*--`) for "owns and manages", implementation (`<|..`) for "fulfills contract", dependency (`..>`) for "uses at runtime". Each arrow type carries meaning.

384
scientific-skills/markdown-mermaid-writing/references/diagrams/complex_examples.md Normal file
View File

@@ -0,0 +1,384 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Composing Complex Diagram Sets
> **Back to [Style Guide](../mermaid_style_guide.md)** — This file covers how to combine multiple diagram types to document complex systems comprehensively.
**Purpose:** A single diagram captures a single perspective. Real documentation often needs multiple diagram types working together — an overview flowchart linked to a detailed sequence diagram, an ER schema paired with a state machine showing entity lifecycle, a Gantt timeline complemented by architecture before/after views. This file teaches you when and how to compose diagrams for maximum clarity.
---
## When to Compose Multiple Diagrams
| What you're documenting | Diagram combination | Why it works |
| ------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Full system architecture | C4 Context + Architecture + Sequence (key flows) | Context for stakeholders, infrastructure for ops, sequences for developers |
| API design documentation | ER (data model) + Sequence (request flows) + State (entity lifecycle) | Schema for the database team, interactions for backend, states for business logic |
| Feature specification | Flowchart (happy path) + Sequence (service interactions) + User Journey (UX) | Process for PM, implementation for engineers, experience for design |
| Migration project | Gantt (timeline) + Architecture (before/after) + Flowchart (migration process) | Schedule for leadership, topology for infra, steps for the migration team |
| Onboarding documentation | User Journey + Flowchart (setup steps) + Sequence (first API call) | Experience map for product, checklist for new hires, technical walkthrough for devs |
| Incident response | State (alert lifecycle) + Sequence (escalation flow) + Flowchart (decision tree) | Status tracking for on-call, communication for management, triage for responders |
---
## Pattern 1: Overview + Detail
**When to use:** You need both the big picture AND the specifics. Leadership sees the overview; engineers drill into the detail.
The overview diagram shows high-level phases or components. One or more detail diagrams zoom into specific phases showing the internal interactions.
### Overview — Release Pipeline
```mermaid
flowchart LR
accTitle: Release Pipeline Overview
accDescr: High-level four-phase release pipeline from code commit through build, staging, and production deployment
subgraph source ["📥 Source"]
commit[📝 Code commit] --> pr_review[🔍 PR review]
end
subgraph build ["🔧 Build"]
compile[⚙️ Compile] --> test[🧪 Test suite]
test --> scan[🔐 Security scan]
end
subgraph staging ["🚀 Staging"]
deploy_stg[☁️ Deploy staging] --> smoke[🧪 Smoke tests]
smoke --> approval{👤 Approved?}
end
subgraph production ["✅ Production"]
canary[🚀 Canary **5%**] --> rollout[🚀 Full **rollout**]
rollout --> monitor[📊 Monitor metrics]
end
source --> build
build --> staging
approval -->|Yes| production
approval -->|No| source
classDef phase_start fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef phase_test fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef phase_deploy fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class commit,pr_review,compile phase_start
class test,scan,smoke,approval phase_test
class deploy_stg,canary,rollout,monitor phase_deploy
```
_The production deployment phase involves multiple service interactions. See the detail sequence below for the canary rollout process._
### Detail — Canary Deployment Sequence
```mermaid
sequenceDiagram
accTitle: Canary Deployment Service Interactions
accDescr: Detailed sequence showing how the CI server orchestrates a canary deployment through the container registry, Kubernetes cluster, and monitoring stack with automated rollback on failure
participant ci as ⚙️ CI Server
participant registry as 📦 Container Registry
participant k8s as ☁️ Kubernetes
participant monitor as 📊 Monitoring
participant oncall as 👤 On-Call Engineer
ci->>registry: 📤 Push tagged image
registry-->>ci: ✅ Image stored
ci->>k8s: 🚀 Deploy canary (5% traffic)
k8s-->>ci: ✅ Canary pods running
ci->>monitor: 📊 Start canary analysis
Note over monitor: ⏰ Observe for 15 minutes
loop 📊 Every 60 seconds
monitor->>k8s: 🔍 Query error rate
k8s-->>monitor: 📊 Metrics response
end
alt ✅ Error rate below threshold
monitor-->>ci: ✅ Canary healthy
ci->>k8s: 🚀 Promote to 100%
k8s-->>ci: ✅ Full rollout complete
ci->>monitor: 📊 Continue monitoring
else ❌ Error rate above threshold
monitor-->>ci: ❌ Canary failing
ci->>k8s: 🔄 Rollback to previous
k8s-->>ci: ✅ Rollback complete
ci->>oncall: ⚠️ Alert: canary failed
Note over oncall: 📋 Investigate root cause
end
```
### How these connect
- The **overview flowchart** shows the full pipeline with subgraph-to-subgraph connections — leadership reads this to understand the release process
- The **detail sequence** zooms into "Canary 5% → Full rollout" from the Production subgraph, showing the actual service interactions an engineer would debug
- **Naming is consistent** — "Canary" and "Monitor metrics" appear in both diagrams, creating a clear bridge between overview and detail
---
## Pattern 2: Multi-Perspective Documentation
**When to use:** The same system needs to be documented for different audiences — database teams, backend engineers, and product managers each need a different view of the same feature.
This example documents a **User Authentication** feature from three perspectives.
### Data Model — for database team
```mermaid
erDiagram
accTitle: Authentication Data Model
accDescr: Five-entity schema for user authentication covering users, sessions, refresh tokens, login attempts, and MFA devices with cardinality relationships
USER ||--o{ SESSION : "has"
USER ||--o{ REFRESH_TOKEN : "owns"
USER ||--o{ LOGIN_ATTEMPT : "produces"
USER ||--o{ MFA_DEVICE : "registers"
SESSION ||--|| REFRESH_TOKEN : "paired with"
USER {
uuid id PK "🔑 Primary key"
string email "📧 Unique login"
string password_hash "🔐 Bcrypt hash"
boolean mfa_enabled "🔒 MFA flag"
timestamp last_login "⏰ Last active"
}
SESSION {
uuid id PK "🔑 Primary key"
uuid user_id FK "👤 Session owner"
string ip_address "🌐 Client IP"
string user_agent "📋 Browser info"
timestamp expires_at "⏰ Expiration"
}
REFRESH_TOKEN {
uuid id PK "🔑 Primary key"
uuid user_id FK "👤 Token owner"
uuid session_id FK "🔗 Paired session"
string token_hash "🔐 Hashed token"
boolean revoked "❌ Revoked flag"
timestamp expires_at "⏰ Expiration"
}
LOGIN_ATTEMPT {
uuid id PK "🔑 Primary key"
uuid user_id FK "👤 Attempting user"
string ip_address "🌐 Source IP"
boolean success "✅ Outcome"
string failure_reason "⚠️ Why failed"
timestamp attempted_at "⏰ Attempt time"
}
MFA_DEVICE {
uuid id PK "🔑 Primary key"
uuid user_id FK "👤 Device owner"
string device_type "📱 TOTP or WebAuthn"
string secret_hash "🔐 Encrypted secret"
boolean verified "✅ Setup complete"
timestamp registered_at "⏰ Registered"
}
```
### Authentication Flow — for backend team
```mermaid
sequenceDiagram
accTitle: Login Flow with MFA
accDescr: Step-by-step authentication sequence showing credential validation, conditional MFA challenge, token issuance, and failure handling between browser, API, auth service, and database
participant B as 👤 Browser
participant API as 🌐 API Gateway
participant Auth as 🔐 Auth Service
participant DB as 💾 Database
B->>API: 📤 POST /login (email, password)
API->>Auth: 🔐 Validate credentials
Auth->>DB: 🔍 Fetch user by email
DB-->>Auth: 👤 User record
Auth->>Auth: 🔐 Verify password hash
alt ❌ Invalid password
Auth->>DB: 📝 Log failed attempt
Auth-->>API: ❌ 401 Unauthorized
API-->>B: ❌ Invalid credentials
else ✅ Password valid
alt 🔒 MFA enabled
Auth-->>API: ⚠️ 202 MFA required
API-->>B: 📱 Show MFA prompt
B->>API: 📤 POST /login/mfa (code)
API->>Auth: 🔐 Verify MFA code
Auth->>DB: 🔍 Fetch MFA device
DB-->>Auth: 📱 Device record
Auth->>Auth: 🔐 Validate TOTP
alt ❌ Invalid code
Auth-->>API: ❌ 401 Invalid code
API-->>B: ❌ Try again
else ✅ Code valid
Auth->>DB: 📝 Create session + tokens
Auth-->>API: ✅ 200 + tokens
API-->>B: ✅ Set cookies + redirect
end
else 🔓 No MFA
Auth->>DB: 📝 Create session + tokens
Auth-->>API: ✅ 200 + tokens
API-->>B: ✅ Set cookies + redirect
end
end
```
### Login Experience — for product team
```mermaid
journey
accTitle: Login Experience Journey Map
accDescr: User satisfaction scores across the sign-in experience for password-only users and MFA users showing friction points in the multi-factor flow
title 👤 Login Experience
section 🔐 Sign In
Navigate to login : 4 : User
Enter email and password : 3 : User
Click sign in button : 4 : User
section 📱 MFA Challenge
Receive MFA prompt : 3 : MFA User
Open authenticator app : 2 : MFA User
Enter 6-digit code : 2 : MFA User
Handle expired code : 1 : MFA User
section ✅ Post-Login
Land on dashboard : 5 : User
See personalized content : 5 : User
Resume previous session : 4 : User
```
### How these connect
- **Same entities, different views** — "User", "Session", "MFA Device" appear in the ER diagram as tables, in the sequence as participants/operations, and in the journey as experience touchpoints
- **Each audience gets actionable information** — the DB team sees indexes and cardinality, the backend team sees API contracts and error codes, the product team sees satisfaction scores and friction points
- **The journey reveals what the sequence hides** — the sequence diagram shows MFA as a clean conditional branch, but the journey map shows it's actually the worst part of the UX (scores 1-2). This drives the product decision to invest in WebAuthn/passkeys
---
## Pattern 3: Before/After Architecture
**When to use:** Migration documentation where stakeholders need to see the current state, the target state, and understand the transformation.
### Current State — Monolith
```mermaid
flowchart TB
accTitle: Current State Monolith Architecture
accDescr: Single Rails monolith handling all traffic through one server connected to one database showing the scaling bottleneck
client([👤 All traffic]) --> mono[🖥️ Rails **Monolith**]
mono --> db[(💾 Single PostgreSQL)]
mono --> jobs[⏰ Background **jobs**]
jobs --> db
classDef bottleneck fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937
class mono,db bottleneck
class client,jobs neutral
```
> ⚠️ **Problem:** Single database is the bottleneck. Monolith can't scale horizontally. Deploy = full restart.
### Target State — Microservices
```mermaid
flowchart TB
accTitle: Target State Microservices Architecture
accDescr: Decomposed microservices architecture with API gateway routing to independent services each with their own data store and a shared message queue for async communication
client([👤 All traffic]) --> gw[🌐 API **Gateway**]
subgraph services ["⚙️ Services"]
user_svc[👤 User Service]
order_svc[📋 Order Service]
product_svc[📦 Product Service]
end
subgraph data ["💾 Data Stores"]
user_db[(💾 Users DB)]
order_db[(💾 Orders DB)]
product_db[(💾 Products DB)]
end
gw --> user_svc
gw --> order_svc
gw --> product_svc
user_svc --> user_db
order_svc --> order_db
product_svc --> product_db
order_svc --> mq[📥 Message Queue]
mq --> user_svc
mq --> product_svc
classDef gateway fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
classDef service fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef datastore fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
classDef infra fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
class gw gateway
class user_svc,order_svc,product_svc service
class user_db,order_db,product_db datastore
class mq infra
```
> ✅ **Result:** Each service scales independently. Database-per-service eliminates the shared bottleneck. Async messaging decouples service dependencies.
### How these connect
- **Same layout, different complexity** — both diagrams use `flowchart TB` so the structural transformation is visually obvious. The monolith is 4 nodes; the target is 11 nodes with subgraphs.
- **Color tells the story** — the monolith uses red (danger) on the bottleneck components. The target uses blue/green/purple to show healthy, differentiated components.
- **Prose bridges the diagrams** — the ⚠️ problem callout and ✅ result callout explain _why_ the architecture changes, not just _what_ changed.
---
## Linking Diagrams in Documentation
When composing diagrams in a real document, follow these practices:
| Practice | Example |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Use headers as anchors** | `See [Authentication Flow](#authentication-flow-for-backend-team) for the full login sequence` |
| **Reference specific nodes** | "The **API Gateway** from the overview connects to the services detailed below" |
| **Consistent naming** | Same entity = same name in every diagram (User Service, not "User Svc" in one and "Users API" in another) |
| **Adjacent placement** | Keep related diagrams in consecutive sections, not scattered across the document |
| **Bridging prose** | One sentence between diagrams explaining how they connect: "The sequence below zooms into the Deploy phase from the pipeline above" |
| **Audience labels** | Mark sections: "### Data Model — _for database team_" so readers skip to their view |
---
## Choosing Your Composition Strategy
```mermaid
flowchart TB
accTitle: Diagram Composition Decision Tree
accDescr: Decision flowchart for choosing between single diagram, overview plus detail, multi-perspective, or before-after composition strategies based on audience and documentation needs
start([📋 What are you documenting?]) --> audience{👥 Multiple audiences?}
audience -->|Yes| perspectives[📐 Multi-Perspective]
audience -->|No| depth{📏 Need both summary and detail?}
depth -->|Yes| overview[🔍 Overview + Detail]
depth -->|No| change{🔄 Showing a change over time?}
change -->|Yes| before_after[⚡ Before / After]
change -->|No| single[📊 Single diagram is fine]
classDef decision fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef result fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef start_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
class audience,depth,change decision
class perspectives,overview,before_after,single result
class start start_style
```

222
scientific-skills/markdown-mermaid-writing/references/diagrams/er.md Normal file
View File

@@ -0,0 +1,222 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Entity Relationship (ER) Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `erDiagram`
**Best for:** Database schemas, data models, entity relationships, API data structures
**When NOT to use:** Class hierarchies with methods (use [Class](class.md)), process flows (use [Flowchart](flowchart.md))
---
## Exemplar Diagram
```mermaid
erDiagram
accTitle: Project Management Data Model
accDescr: Entity relationships for a project management system showing teams, projects, tasks, members, and comments with cardinality
TEAM ||--o{ PROJECT : "owns"
PROJECT ||--o{ TASK : "contains"
TASK ||--o{ COMMENT : "has"
TEAM ||--o{ MEMBER : "includes"
MEMBER ||--o{ TASK : "assigned to"
MEMBER ||--o{ COMMENT : "writes"
TEAM {
uuid id PK "🔑 Primary key"
string name "👥 Team name"
string department "🏢 Department"
}
PROJECT {
uuid id PK "🔑 Primary key"
uuid team_id FK "🔗 Team reference"
string title "📋 Project title"
string status "📊 Current status"
date deadline "⏰ Due date"
}
TASK {
uuid id PK "🔑 Primary key"
uuid project_id FK "🔗 Project reference"
uuid assignee_id FK "👤 Assigned member"
string title "📝 Task title"
string priority "⚠️ Priority level"
string status "📊 Current status"
}
MEMBER {
uuid id PK "🔑 Primary key"
uuid team_id FK "🔗 Team reference"
string name "👤 Full name"
string email "📧 Email address"
string role "🏷️ Job role"
}
COMMENT {
uuid id PK "🔑 Primary key"
uuid task_id FK "🔗 Task reference"
uuid author_id FK "👤 Author reference"
text body "📝 Comment text"
timestamp created_at "⏰ Created time"
}
```
---
## Tips
- Include data types, `PK`/`FK` annotations, and **comment strings** with emoji for context
- Use clear verb-phrase relationship labels: `"owns"`, `"contains"`, `"assigned to"`
- Cardinality notation:
- `||--o{` one-to-many
- `||--||` one-to-one
- `}o--o{` many-to-many
- `o` = zero or more, `|` = exactly one
- Limit to **5–7 entities** per diagram — split large schemas by domain
- Entity names: `UPPER_CASE` (SQL convention)
---
## Template
```mermaid
erDiagram
accTitle: Your Title Here
accDescr: Describe the data model and key relationships between entities
ENTITY_A ||--o{ ENTITY_B : "has many"
ENTITY_B ||--|| ENTITY_C : "belongs to"
ENTITY_A {
uuid id PK "🔑 Primary key"
string name "📝 Display name"
}
ENTITY_B {
uuid id PK "🔑 Primary key"
uuid entity_a_id FK "🔗 Reference"
string value "📊 Value field"
}
```
---
## Complex Example
A multi-tenant SaaS platform schema with 10 entities spanning three domains — identity & access, billing & subscriptions, and audit & security. Relationships show the full cardinality picture from tenant isolation through user permissions to invoice generation.
```mermaid
erDiagram
accTitle: SaaS Multi-Tenant Platform Schema
accDescr: Ten-entity data model for a multi-tenant SaaS platform covering identity management, role-based access, subscription billing, and audit logging with full cardinality relationships
TENANT ||--o{ ORGANIZATION : "contains"
ORGANIZATION ||--o{ USER : "employs"
ORGANIZATION ||--|| SUBSCRIPTION : "holds"
USER }o--o{ ROLE : "assigned"
ROLE ||--o{ PERMISSION : "grants"
SUBSCRIPTION ||--|| PLAN : "subscribes to"
SUBSCRIPTION ||--o{ INVOICE : "generates"
USER ||--o{ AUDIT_LOG : "produces"
TENANT ||--o{ AUDIT_LOG : "scoped to"
USER ||--o{ API_KEY : "owns"
TENANT {
uuid id PK "🔑 Primary key"
string name "🏢 Tenant name"
string subdomain "🌐 Unique subdomain"
string tier "🏷️ Service tier"
boolean active "✅ Active status"
timestamp created_at "⏰ Created time"
}
ORGANIZATION {
uuid id PK "🔑 Primary key"
uuid tenant_id FK "🔗 Tenant reference"
string name "👥 Org name"
string billing_email "📧 Billing contact"
int seat_count "📊 Licensed seats"
}
USER {
uuid id PK "🔑 Primary key"
uuid org_id FK "🔗 Organization reference"
string email "📧 Login email"
string display_name "👤 Display name"
string status "📊 Account status"
timestamp last_login "⏰ Last active"
}
ROLE {
uuid id PK "🔑 Primary key"
uuid tenant_id FK "🔗 Tenant scope"
string name "🏷️ Role name"
string description "📝 Role purpose"
boolean system_role "🔒 Built-in flag"
}
PERMISSION {
uuid id PK "🔑 Primary key"
uuid role_id FK "🔗 Role reference"
string resource "🎯 Target resource"
string action "⚙️ Allowed action"
string scope "🔒 Permission scope"
}
PLAN {
uuid id PK "🔑 Primary key"
string name "🏷️ Plan name"
int price_cents "💰 Monthly price"
int seat_limit "👥 Max seats"
jsonb features "📋 Feature flags"
boolean active "✅ Available flag"
}
SUBSCRIPTION {
uuid id PK "🔑 Primary key"
uuid org_id FK "🔗 Organization reference"
uuid plan_id FK "🔗 Plan reference"
string status "📊 Sub status"
date current_period_start "📅 Period start"
date current_period_end "📅 Period end"
}
INVOICE {
uuid id PK "🔑 Primary key"
uuid subscription_id FK "🔗 Subscription reference"
int amount_cents "💰 Total amount"
string currency "💱 Currency code"
string status "📊 Payment status"
timestamp issued_at "⏰ Issue date"
}
AUDIT_LOG {
uuid id PK "🔑 Primary key"
uuid tenant_id FK "🔗 Tenant scope"
uuid user_id FK "👤 Acting user"
string action "⚙️ Action performed"
string resource_type "🎯 Target type"
uuid resource_id "🔗 Target ID"
jsonb metadata "📋 Event details"
timestamp created_at "⏰ Event time"
}
API_KEY {
uuid id PK "🔑 Primary key"
uuid user_id FK "👤 Owner"
string prefix "🏷️ Key prefix"
string hash "🔐 Hashed secret"
string name "📝 Key name"
timestamp expires_at "⏰ Expiration"
boolean revoked "❌ Revoked flag"
}
```
### Why this works
- **10 entities organized by domain** — identity (Tenant, Organization, User, Role, Permission), billing (Plan, Subscription, Invoice), and security (Audit Log, API Key). The relationship lines naturally cluster related entities together.
- **Full cardinality tells the business rules** — `||--||` (one-to-one) for Organization-Subscription means one subscription per org. `}o--o{` (many-to-many) for User-Role means flexible RBAC. Each relationship symbol encodes a constraint.
- **Every field has type, annotation, and purpose** — PK/FK for schema generation, emoji comments for human scanning. A developer can read this diagram and write the migration script directly.

177
scientific-skills/markdown-mermaid-writing/references/diagrams/flowchart.md Normal file
View File

@@ -0,0 +1,177 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Flowchart
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `flowchart`
**Best for:** Sequential processes, workflows, decision logic, troubleshooting trees
**When NOT to use:** Complex timing between actors (use [Sequence](sequence.md)), state machines (use [State](state.md))
---
## Exemplar Diagram
```mermaid
flowchart TB
accTitle: Feature Development Lifecycle
accDescr: End-to-end feature flow from idea through design, build, test, review, and release with a revision loop on failed reviews
idea([💡 Feature idea]) --> spec[📋 Write spec]
spec --> design[🎨 Design solution]
design --> build[🔧 Implement]
build --> test[🧪 Run tests]
test --> review{🔍 Review passed?}
review -->|Yes| release[🚀 Release to prod]
review -->|No| revise[✏️ Revise code]
revise --> test
release --> monitor([📊 Monitor metrics])
classDef start fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
classDef process fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef decision fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef success fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class idea,monitor start
class spec,design,build,test,revise process
class review decision
class release success
```
---
## Tips
- Use `TB` (top-to-bottom) for processes, `LR` (left-to-right) for pipelines
- Rounded rectangles `([text])` for start/end, diamonds `{text}` for decisions
- Max 10 nodes — split larger flows into "Phase 1" / "Phase 2" diagrams
- Max 3 decision points per diagram
- Edge labels should be 1–4 words: `-->|Yes|`, `-->|All green|`
- Use `classDef` for **semantic** coloring — decisions in amber, success in green, actions in blue
## Subgraph Pattern
When you need grouped stages:
```mermaid
flowchart TB
accTitle: CI/CD Pipeline Stages
accDescr: Three-stage pipeline grouping code quality checks, testing, and deployment into distinct phases
trigger([⚡ Push to main])
subgraph quality ["🔍 Code Quality"]
lint[📝 Lint code] --> format[⚙️ Check formatting]
end
subgraph testing ["🧪 Testing"]
unit[🧪 Unit tests] --> integration[🔗 Integration tests]
end
subgraph deploy ["🚀 Deployment"]
build[📦 Build artifacts] --> ship[☁️ Deploy to staging]
end
trigger --> quality
quality --> testing
testing --> deploy
deploy --> done([✅ Pipeline complete])
classDef trigger_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
classDef success fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class trigger trigger_style
class done success
```
---
## Template
```mermaid
flowchart TB
accTitle: Your Title Here (3-8 words)
accDescr: One or two sentences explaining what this diagram shows and what insight the reader gains
start([🏁 Starting point]) --> step1[⚙️ First action]
step1 --> decision{🔍 Check condition?}
decision -->|Yes| step2[✅ Positive path]
decision -->|No| step3[🔧 Alternative path]
step2 --> done([🏁 Complete])
step3 --> done
```
---
## Complex Example
A 20+ node e-commerce order pipeline organized into 5 subgraphs, each representing a processing phase. Subgraphs connect through internal nodes, decision points route orders to exception handling, and color classes distinguish phases at a glance.
```mermaid
flowchart TB
accTitle: E-Commerce Order Processing Pipeline
accDescr: Full order lifecycle from intake through fulfillment, shipping, and notification with exception handling paths for payment failures, stockouts, and delivery issues
order_in([📥 New order]) --> validate_pay{💰 Payment valid?}
subgraph intake ["📥 Order Intake"]
validate_pay -->|Yes| check_fraud{🔐 Fraud check}
validate_pay -->|No| pay_fail[❌ Payment **declined**]
check_fraud -->|Clear| check_stock{📦 In stock?}
check_fraud -->|Flagged| manual_review[🔍 Manual **review**]
manual_review --> check_stock
end
subgraph fulfill ["📦 Fulfillment"]
pick[📋 **Pick** items] --> pack[📦 Pack order]
pack --> label[🏷️ Generate **shipping** label]
end
subgraph ship ["🚚 Shipping"]
handoff[🚚 Carrier **handoff**] --> transit[📍 In transit]
transit --> deliver{✅ Delivered?}
end
subgraph notify ["📤 Notifications"]
confirm_email[📧 Order **confirmed**]
ship_update[📧 Shipping **update**]
deliver_email[📧 Delivery **confirmed**]
end
subgraph exception ["⚠️ Exception Handling"]
pay_fail --> retry_pay[🔄 Retry payment]
retry_pay --> validate_pay
out_of_stock[📦 **Backorder** created]
deliver_fail[🔄 **Reattempt** delivery]
end
check_stock -->|Yes| pick
check_stock -->|No| out_of_stock
label --> handoff
deliver -->|Yes| deliver_email
deliver -->|No| deliver_fail
deliver_fail --> transit
check_stock -->|Yes| confirm_email
handoff --> ship_update
deliver_email --> complete([✅ Order **complete**])
classDef intake_style fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef fulfill_style fill:#ede9fe,stroke:#7c3aed,stroke-width:2px,color:#3b0764
classDef ship_style fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
classDef warn_style fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef danger_style fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
class validate_pay,check_fraud,check_stock,manual_review intake_style
class pick,pack,label fulfill_style
class handoff,transit,deliver ship_style
class confirm_email,ship_update,deliver_email warn_style
class pay_fail,retry_pay,out_of_stock,deliver_fail danger_style
```
### Why this works
- **5 subgraphs map to real business phases** — intake, fulfillment, shipping, notification, and exceptions are how operations teams actually think about orders
- **Exception handling is its own subgraph** — not scattered across phases. Agents and readers can see all failure paths in one place
- **Color classes reinforce structure** — blue for intake, purple for fulfillment, green for shipping, amber for notifications, red for exceptions. Even without reading labels, the color pattern tells you which phase you're looking at
- **Decisions route between subgraphs** — the diamonds (`{Payment valid?}`, `{In stock?}`, `{Delivered?}`) are the points where flow branches, and each branch leads to a clearly-labeled destination

138
scientific-skills/markdown-mermaid-writing/references/diagrams/gantt.md Normal file
View File

@@ -0,0 +1,138 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Gantt Chart
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `gantt`
**Best for:** Project timelines, roadmaps, phase planning, milestone tracking, task dependencies
**When NOT to use:** Simple chronological events (use [Timeline](timeline.md)), process logic (use [Flowchart](flowchart.md))
---
## Exemplar Diagram
```mermaid
gantt
accTitle: Q1 Product Launch Roadmap
accDescr: Eight-week project timeline across discovery, design, build, and launch phases with milestones for design review and go/no-go decision
title 🚀 Q1 Product Launch Roadmap
dateFormat YYYY-MM-DD
axisFormat %b %d
section 📋 Discovery
User research :done, research, 2026-01-05, 7d
Competitive analysis :done, compete, 2026-01-05, 5d
Requirements doc :done, reqs, after compete, 3d
section 🎨 Design
Wireframes :done, wire, after reqs, 5d
Visual design :active, visual, after wire, 7d
🏁 Design review :milestone, review, after visual, 0d
section 🔧 Build
Core features :crit, core, after visual, 10d
API integration :api, after visual, 8d
Testing :test, after core, 5d
section 🚀 Launch
Staging deploy :staging, after test, 3d
🏁 Go / no-go :milestone, decision, after staging, 0d
Production release :crit, release, after staging, 2d
```
---
## Tips
- Use `section` with emoji prefix to group by phase or team
- Mark milestones with `:milestone` and `0d` duration — prefix with 🏁
- Status tags: `:done`, `:active`, `:crit` (critical path, highlighted)
- Use `after taskId` for dependencies
- Keep total timeline **under 3 months** for readability
- Use `axisFormat` to control date display (`%b %d` = "Jan 05", `%m/%d` = "01/05")
---
## Template
```mermaid
gantt
accTitle: Your Title Here
accDescr: Describe the timeline scope and key milestones
title 📋 Your Roadmap Title
dateFormat YYYY-MM-DD
axisFormat %b %d
section 📋 Phase 1
Task one :done, t1, 2026-01-01, 5d
Task two :active, t2, after t1, 3d
section 🔧 Phase 2
Task three :crit, t3, after t2, 7d
🏁 Milestone :milestone, m1, after t3, 0d
```
---
## Complex Example
A cross-team platform migration spanning 4 months with 6 sections, 24 tasks, and 3 milestones. Shows dependencies across teams (backend migration blocks frontend migration), critical path items, and the full lifecycle from planning through launch monitoring.
```mermaid
gantt
accTitle: Multi-Team Platform Migration Roadmap
accDescr: Four-month migration project across planning, backend, frontend, data, QA, and launch teams with cross-team dependencies, critical path items, and three milestone gates
title 🚀 Platform Migration — Q1/Q2 2026
dateFormat YYYY-MM-DD
axisFormat %b %d
section 📋 Planning
Kickoff meeting :done, plan1, 2026-01-05, 2d
Architecture review :done, plan2, after plan1, 5d
Migration plan document :done, plan3, after plan2, 5d
Risk assessment :done, plan4, after plan2, 3d
🏁 Planning complete :milestone, m_plan, after plan3, 0d
section 🔧 Backend Team
API redesign :crit, be1, after m_plan, 12d
Data migration scripts :be2, after m_plan, 10d
New service deployment :crit, be3, after be1, 8d
Backward compatibility layer :be4, after be1, 6d
section 🎨 Frontend Team
Component library update :fe1, after m_plan, 10d
Page migration :crit, fe2, after be3, 12d
A/B testing setup :fe3, after fe2, 5d
Feature parity validation :fe4, after fe2, 4d
section 🗄️ Data Team
Schema migration :crit, de1, after be2, 8d
ETL pipeline update :de2, after de1, 7d
Data validation suite :de3, after de2, 5d
Rollback scripts :de4, after de1, 4d
section 🧪 QA Team
Test plan creation :qa1, after m_plan, 7d
Regression suite :qa2, after be3, 10d
Performance testing :crit, qa3, after qa2, 7d
UAT coordination :qa4, after qa3, 5d
🏁 QA sign-off :milestone, m_qa, after qa4, 0d
section 🚀 Launch
Staging deploy :crit, l1, after m_qa, 3d
🏁 Go / no-go decision :milestone, m_go, after l1, 0d
Production cutover :crit, l2, after m_go, 2d
Post-launch monitoring :l3, after l2, 10d
Legacy system decommission :l4, after l3, 5d
```
### Why this works
- **6 sections map to real teams** — each team sees their workstream at a glance. Cross-team dependencies (frontend waits for backend API, QA waits for backend deploy) are explicit via `after taskId`.
- **`:crit` marks the critical path** — the chain of tasks that determines the total project duration. If any critical task slips, the launch date moves. Mermaid highlights these in red.
- **3 milestones are decision gates** — Planning Complete, QA Sign-off, and Go/No-Go. These are the points where stakeholders make decisions, not just status updates.
- **24 tasks across 4 months** is readable because sections group by team. Without sections, this would be an unreadable wall of bars.

74
scientific-skills/markdown-mermaid-writing/references/diagrams/git_graph.md Normal file
View File

@@ -0,0 +1,74 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Git Graph
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `gitGraph`
**Best for:** Branching strategies, merge workflows, release processes, git-flow visualization
**When NOT to use:** General processes (use [Flowchart](flowchart.md)), project timelines (use [Gantt](gantt.md))
---
## Exemplar Diagram
```mermaid
gitGraph
accTitle: Trunk-Based Development Workflow
accDescr: Git history showing short-lived feature branches merging into main with release tags demonstrating trunk-based development
commit id: "init"
commit id: "setup CI"
branch feature/auth
checkout feature/auth
commit id: "add login"
commit id: "add tests"
checkout main
merge feature/auth id: "merge auth" tag: "v1.0"
commit id: "update deps"
branch feature/dashboard
checkout feature/dashboard
commit id: "add charts"
commit id: "add filters"
checkout main
merge feature/dashboard id: "merge dash"
commit id: "perf fixes" tag: "v1.1"
```
---
## Tips
- Use descriptive `id:` labels on commits
- Add `tag:` for release versions
- Branch names should match your actual convention (`feature/`, `fix/`, `release/`)
- Show the **ideal** workflow — this is prescriptive, not descriptive
- Use `type: HIGHLIGHT` on important merge commits
- Keep to **10–15 commits** maximum for readability
---
## Template
```mermaid
gitGraph
accTitle: Your Title Here
accDescr: Describe the branching strategy and merge pattern
commit id: "initial"
commit id: "second commit"
branch feature/your-feature
checkout feature/your-feature
commit id: "feature work"
commit id: "add tests"
checkout main
merge feature/your-feature id: "merge feature" tag: "v1.0"
```

107
scientific-skills/markdown-mermaid-writing/references/diagrams/kanban.md Normal file
View File

@@ -0,0 +1,107 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Kanban Board
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `kanban`
**Best for:** Task status boards, workflow columns, work-in-progress visualization, sprint status
**When NOT to use:** Task timelines/dependencies (use [Gantt](gantt.md)), process logic (use [Flowchart](flowchart.md))
> ⚠️ **Accessibility:** Kanban boards do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Kanban board showing the current sprint's work items distributed across four workflow columns, with emoji indicating column status:_
```mermaid
kanban
Backlog
task1[🔐 Upgrade auth library]
task2[🛡️ Add rate limiting]
task3[📚 Write API docs]
In Progress
task4[📊 Build dashboard]
task5[🐛 Fix login bug]
In Review
task6[💰 Refactor payments]
Done
task7[📊 Deploy monitoring]
task8[⚙️ Update CI pipeline]
```
> ⚠️ **Tip:** Each task gets ONE domain emoji at the start — this is your primary visual signal for categorization. Column emoji indicates workflow state.
---
## Tips
- Name columns with **status emoji** for instant visual scanning
- Add **domain emoji** to tasks for quick categorization
- Keep to **3–5 columns**
- Limit to **3–4 items per column** (representative, not exhaustive)
- Items are simple text descriptions — keep concise
- Good for sprint snapshots in documentation
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of the workflow columns and what the board represents. Always show all 6 columns:_
```mermaid
kanban
Backlog
task1[🔧 Task description]
task2[📝 Task description]
In Progress
task3[⚙️ Task description]
In Review
task4[👀 Task description]
Done
task5[🚀 Task description]
Blocked
task6[⛔ Task description]
Won't Do
task7[❌ Task description]
```
> ⚠️ Always include all 6 columns — Backlog, In Progress, In Review, Done, Blocked, Won't Do. Even if a column is empty, include a placeholder item like [No items yet] to make the structure explicit.
---
## Complex Example
_Sprint W07 board for the Payments Team showing a realistic distribution of work items across all six columns, including blocked items:_
```mermaid
kanban
Backlog
b1[📊 Add pool monitoring to auth]
b2[🔍 Evaluate PgBouncer]
b3[📝 Update runbook for pool alerts]
In Progress
ip1[📊 Build merchant dashboard MVP]
ip2[📚 Write v2 API migration guide]
ip3[🔐 Add OAuth2 PKCE flow]
In Review
r1[🛡️ Request validation middleware]
Done
d1[🛡️ Rate limiting on /v2/charges]
d2[🐛 Fix pool exhaustion errors]
d3[📊 Pool utilization alerts]
Blocked
bl1[🔄 Auth service pool config]
Won't Do
w1[❌ Mobile SDK in this sprint]
```
Tips for complex kanban diagrams:
- Add a Blocked column to surface stalled work — this is the highest-signal column on any board
- Keep items to 3–4 per column max even in complex boards — the diagram is a summary, not an exhaustive list
- Use the same emoji per domain across columns for visual tracking (📊 = dashboards, 🛡️ = security, 🐛 = bugs)
- Always show all 6 columns — use placeholder items like [No items] when a column is empty

74
scientific-skills/markdown-mermaid-writing/references/diagrams/mindmap.md Normal file
View File

@@ -0,0 +1,74 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Mindmap
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `mindmap`
**Best for:** Brainstorming, concept organization, knowledge hierarchies, topic breakdown
**When NOT to use:** Sequential processes (use [Flowchart](flowchart.md)), timelines (use [Timeline](timeline.md))
> ⚠️ **Accessibility:** Mindmaps do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Mindmap showing a platform engineering team's key responsibility areas organized into infrastructure, developer experience, security, and observability domains:_
```mermaid
mindmap
root((🏗️ Platform Engineering))
☁️ Infrastructure
Kubernetes clusters
Service mesh
Load balancing
Auto-scaling
🔧 Developer Experience
CI/CD pipelines
Local dev environments
Internal CLI tools
Documentation
🔐 Security
Secret management
Network policies
Vulnerability scanning
Access control
📊 Observability
Metrics collection
Log aggregation
Distributed tracing
Alerting rules
```
---
## Tips
- Keep to **3–4 main branches** with **3–5 sub-items** each
- Use emoji on branch headers for visual distinction
- Don't nest deeper than 3 levels
- Root node uses `(( ))` for circle shape
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of what this mindmap shows and the key categories it covers:_
```mermaid
mindmap
root((🎯 Central Concept))
📋 Branch One
Sub-item A
Sub-item B
Sub-item C
🔧 Branch Two
Sub-item D
Sub-item E
📊 Branch Three
Sub-item F
Sub-item G
Sub-item H
```

55
scientific-skills/markdown-mermaid-writing/references/diagrams/packet.md Normal file
View File

@@ -0,0 +1,55 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Packet Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `packet-beta`
**Best for:** Network protocol headers, data structure layouts, binary format documentation, bit-level specifications
**When NOT to use:** General data models (use [ER](er.md)), system architecture (use [C4](c4.md) or [Architecture](architecture.md))
> ⚠️ **Accessibility:** Packet diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Packet diagram showing the structure of a simplified TCP header with field sizes in bits:_
```mermaid
packet-beta
0-15: "Source Port"
16-31: "Destination Port"
32-63: "Sequence Number"
64-95: "Acknowledgment Number"
96-99: "Data Offset"
100-105: "Reserved"
106-111: "Flags (URG,ACK,PSH,RST,SYN,FIN)"
112-127: "Window Size"
128-143: "Checksum"
144-159: "Urgent Pointer"
```
---
## Tips
- Ranges are `start-end:` in bits (0-indexed)
- Keep field labels concise — abbreviate if needed
- Use for any fixed-width binary format, not just network packets
- Row width defaults to 32 bits — fields wrap naturally
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of the protocol or data format and its field structure:_
```mermaid
packet-beta
0-7: "Field A"
8-15: "Field B"
16-31: "Field C"
32-63: "Field D"
```

52
scientific-skills/markdown-mermaid-writing/references/diagrams/pie.md Normal file
View File

@@ -0,0 +1,52 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Pie Chart
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `pie`
**Best for:** Simple proportional breakdowns, budget allocation, composition, survey results
**When NOT to use:** Trends over time (use [XY Chart](xy_chart.md)), exact comparisons (use a table), more than 7 categories
---
## Exemplar Diagram
```mermaid
pie
accTitle: Engineering Time Allocation
accDescr: Pie chart showing how engineering team time is distributed across feature work, tech debt, bug fixes, on-call, and learning
title 📊 Engineering Time Allocation
"🔧 Feature development" : 45
"🔄 Tech debt reduction" : 20
"🐛 Bug fixes" : 20
"📱 On-call & support" : 10
"📚 Learning & growth" : 5
```
---
## Tips
- Values are proportional — they don't need to sum to 100
- Use descriptive labels with **emoji prefix** for visual distinction
- Limit to **7 slices maximum** — group small ones into "📦 Other"
- Always include a `title` with relevant emoji
- Order slices largest to smallest for readability
---
## Template
```mermaid
pie
accTitle: Your Title Here
accDescr: Describe what proportions are being shown
title 📊 Your Chart Title
"📋 Category A" : 40
"🔧 Category B" : 30
"📦 Category C" : 20
"🗂️ Other" : 10
```

66
scientific-skills/markdown-mermaid-writing/references/diagrams/quadrant.md Normal file
View File

@@ -0,0 +1,66 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Quadrant Chart
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `quadrantChart`
**Best for:** Prioritization matrices, risk assessment, two-axis comparisons, effort/impact analysis
**When NOT to use:** Time-based data (use [Gantt](gantt.md) or [XY Chart](xy_chart.md)), simple rankings (use a table)
> ⚠️ **Accessibility:** Quadrant charts do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Priority matrix plotting engineering initiatives by effort required versus business impact, helping teams decide what to build next:_
```mermaid
quadrantChart
title 🎯 Engineering Priority Matrix
x-axis Low Effort --> High Effort
y-axis Low Impact --> High Impact
quadrant-1 Do First
quadrant-2 Plan Carefully
quadrant-3 Reconsider
quadrant-4 Quick Wins
Upgrade auth library: [0.3, 0.9]
Migrate to new DB: [0.9, 0.8]
Fix typos in docs: [0.1, 0.2]
Add dark mode: [0.4, 0.6]
Rewrite legacy API: [0.95, 0.95]
Update CI cache: [0.15, 0.5]
Add unit tests: [0.5, 0.7]
```
---
## Tips
- Label axes with `Low X --> High X` format
- Name all four quadrants with **actionable** labels
- Plot items as `Name: [x, y]` with values 0.0–1.0
- Limit to **5–10 items** — more becomes cluttered
- Quadrant numbering: 1=top-right, 2=top-left, 3=bottom-left, 4=bottom-right
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of the two axes and what the quadrant placement means:_
```mermaid
quadrantChart
title 🎯 Your Matrix Title
x-axis Low X Axis --> High X Axis
y-axis Low Y Axis --> High Y Axis
quadrant-1 High Both
quadrant-2 High Y Only
quadrant-3 Low Both
quadrant-4 High X Only
Item A: [0.3, 0.8]
Item B: [0.7, 0.6]
Item C: [0.2, 0.3]
```

59
scientific-skills/markdown-mermaid-writing/references/diagrams/radar.md Normal file
View File

@@ -0,0 +1,59 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Radar Chart
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `radar-beta`
**Mermaid version:** v11.6.0+
**Best for:** Multi-dimensional comparisons, skill assessments, performance profiles, competitive analysis
**When NOT to use:** Time series data (use [XY Chart](xy_chart.md)), simple proportions (use [Pie](pie.md))
> ⚠️ **Accessibility:** Radar charts do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Radar chart comparing two engineering candidates across six core competency areas, showing complementary strengths:_
```mermaid
radar-beta
title Team Skill Assessment
axis sys["System Design"], algo["Algorithms"], comms["Communication"], team["Teamwork"], ops["DevOps"], acq["Domain Knowledge"]
curve candidate_a["Candidate A"]{4, 3, 5, 5, 2, 3}
curve candidate_b["Candidate B"]{2, 5, 3, 3, 5, 4}
max 5
graticule polygon
ticks 5
showLegend true
```
---
## Tips
- Define axes with `axis id["Label"]` — use short labels (1–2 words)
- Define curves with `curve id["Label"]{val1, val2, ...}` matching axis order
- Set `max` to normalize all values to the same scale
- `graticule` options: `circle` (default) or `polygon`
- `ticks` controls the number of concentric rings (default 5)
- `showLegend true` adds a legend for multiple curves
- Keep to **5–8 axes** and **2–4 curves** for readability
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of what dimensions are being compared across which entities:_
```mermaid
radar-beta
title Your Radar Title
axis dim1["Dimension 1"], dim2["Dimension 2"], dim3["Dimension 3"], dim4["Dimension 4"], dim5["Dimension 5"]
curve series_a["Series A"]{3, 4, 2, 5, 3}
curve series_b["Series B"]{5, 2, 4, 3, 4}
max 5
showLegend true
```

88
scientific-skills/markdown-mermaid-writing/references/diagrams/requirement.md Normal file
View File

@@ -0,0 +1,88 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Requirement Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `requirementDiagram`
**Best for:** System requirements traceability, compliance mapping, formal requirements engineering
**When NOT to use:** Informal task tracking (use [Kanban](kanban.md)), general relationships (use [ER](er.md))
---
## Exemplar Diagram
```mermaid
requirementDiagram
requirement high_availability {
id: 1
text: System shall maintain 99.9 percent uptime
risk: high
verifymethod: test
}
requirement data_encryption {
id: 2
text: All data at rest shall be AES-256 encrypted
risk: medium
verifymethod: inspection
}
requirement session_timeout {
id: 3
text: Sessions expire after 30 minutes idle
risk: low
verifymethod: test
}
element auth_service {
type: service
docref: auth-service-v2
}
element crypto_module {
type: module
docref: crypto-lib-v3
}
auth_service - satisfies -> high_availability
auth_service - satisfies -> session_timeout
crypto_module - satisfies -> data_encryption
```
---
## Tips
- Each requirement needs: `id`, `text`, `risk`, `verifymethod`
- **`id` must be numeric** — use `id: 1`, `id: 2`, etc. (dashes like `REQ-001` can cause parse errors)
- Risk levels: `low`, `medium`, `high` (all lowercase)
- Verify methods: `analysis`, `inspection`, `test`, `demonstration` (all lowercase)
- Use `element` for design components that satisfy requirements
- Relationship types: `- satisfies ->`, `- traces ->`, `- contains ->`, `- derives ->`, `- refines ->`, `- copies ->`
- Keep to **3–5 requirements** per diagram
- Avoid special characters in text fields — spell out symbols (e.g., "99.9 percent" not "99.9%")
- Use 4-space indentation inside `{ }` blocks
---
## Template
```mermaid
requirementDiagram
requirement your_requirement {
id: 1
text: The requirement statement here
risk: medium
verifymethod: test
}
element your_component {
type: service
docref: component-ref
}
your_component - satisfies -> your_requirement
```

71
scientific-skills/markdown-mermaid-writing/references/diagrams/sankey.md Normal file
View File

@@ -0,0 +1,71 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Sankey Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `sankey-beta`
**Best for:** Flow magnitude visualization, resource distribution, budget allocation, traffic routing
**When NOT to use:** Simple proportions (use [Pie](pie.md)), process steps (use [Flowchart](flowchart.md))
> ⚠️ **Accessibility:** Sankey diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Sankey diagram showing how a $100K monthly cloud budget flows from the total allocation through service categories (compute, storage, networking, observability) to specific AWS services, with band widths proportional to cost:_
```mermaid
sankey-beta
Cloud Budget,Compute,45000
Cloud Budget,Storage,25000
Cloud Budget,Networking,15000
Cloud Budget,Observability,10000
Cloud Budget,Security,5000
Compute,EC2 Instances,30000
Compute,Lambda Functions,10000
Compute,ECS Containers,5000
Storage,S3 Buckets,15000
Storage,RDS Databases,10000
Networking,CloudFront CDN,8000
Networking,API Gateway,7000
Observability,CloudWatch,6000
Observability,Datadog,4000
```
---
## Tips
- Format: `Source,Target,Value` — one flow per line
- Values determine the width of each flow band
- Keep to **3 levels** maximum (source → category → destination)
- Blank lines between groups improve source readability
- Good for answering "where does the 💰 go?" questions
- No emoji in node names (parser limitation) — use descriptive text
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of what flows from where to where and what the magnitudes represent:_
```mermaid
sankey-beta
Source,Category A,500
Source,Category B,300
Source,Category C,200
Category A,Destination 1,300
Category A,Destination 2,200
Category B,Destination 3,300
```

174
scientific-skills/markdown-mermaid-writing/references/diagrams/sequence.md Normal file
View File

@@ -0,0 +1,174 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Sequence Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `sequenceDiagram`
**Best for:** API interactions, temporal flows, multi-actor communication, request/response patterns
**When NOT to use:** Simple linear processes (use [Flowchart](flowchart.md)), static relationships (use [Class](class.md) or [ER](er.md))
---
## Exemplar Diagram
```mermaid
sequenceDiagram
accTitle: OAuth 2.0 Authorization Code Flow
accDescr: Step-by-step OAuth flow between user browser, app server, and identity provider showing the token exchange and error path
participant U as 👤 User Browser
participant A as 🖥️ App Server
participant I as 🔐 Identity Provider
U->>A: Click Sign in
A-->>U: Redirect to IdP
U->>I: Enter credentials
I->>I: 🔍 Validate credentials
alt ✅ Valid credentials
I-->>U: Redirect with auth code
U->>A: Send auth code
A->>I: Exchange code for token
I-->>A: 🔐 Access + refresh token
A-->>U: ✅ Set session cookie
Note over U,A: 🔒 User is now authenticated
else ❌ Invalid credentials
I-->>U: ⚠️ Show error message
end
```
---
## Tips
- Limit to **4–5 participants** — more becomes unreadable
- Solid arrows (`->>`) for requests, dashed (`-->>`) for responses
- Use `alt/else/end` for conditional branches
- Use `Note over X,Y:` for contextual annotations with emoji
- Use `par/end` for parallel operations
- Use `loop/end` for repeated interactions
- Emoji in **message text** works great for status clarity (✅, ❌, ⚠️, 🔐)
## Common Patterns
**Parallel calls:**
```
par 📥 Fetch user
A->>B: GET /user
and 📥 Fetch orders
A->>C: GET /orders
end
```
**Loops:**
```
loop ⏰ Every 30 seconds
A->>B: Health check
B-->>A: ✅ 200 OK
end
```
---
## Template
```mermaid
sequenceDiagram
accTitle: Your Title Here
accDescr: Describe the interaction between participants and what the sequence demonstrates
participant A as 👤 Actor
participant B as 🖥️ System
participant C as 💾 Database
A->>B: 📤 Request action
B->>C: 🔍 Query data
C-->>B: 📥 Return results
B-->>A: ✅ Deliver response
```
---
## Complex Example
A microservices checkout flow with 6 participants grouped in `box` regions. Shows parallel calls, conditional branching, error handling with `break`, retry logic, and contextual notes — the full toolkit for complex sequences.
```mermaid
sequenceDiagram
accTitle: Microservices Checkout Flow
accDescr: Multi-service checkout sequence showing parallel inventory and payment processing, error recovery with retries, and async notification dispatch across client, gateway, and backend service layers
box rgb(237,233,254) 🌐 Client Layer
participant browser as 👤 Browser
end
box rgb(219,234,254) 🖥️ API Layer
participant gw as 🌐 API Gateway
participant order as 📋 Order Service
end
box rgb(220,252,231) ⚙️ Backend Services
participant inventory as 📦 Inventory
participant payment as 💰 Payment
participant notify as 📤 Notifications
end
browser->>gw: 🛒 Submit checkout
gw->>gw: 🔐 Validate JWT token
gw->>order: 📋 Create order
Note over order: 📊 Order status: PENDING
par ⚡ Parallel validation
order->>inventory: 📦 Reserve items
inventory-->>order: ✅ Items reserved
and
order->>payment: 💰 Authorize card
payment-->>order: ✅ Payment authorized
end
alt ✅ Both succeeded
order->>payment: 💰 Capture payment
payment-->>order: ✅ Payment captured
order->>inventory: 📦 Confirm reservation
Note over order: 📊 Order status: CONFIRMED
par 📤 Async notifications
order->>notify: 📧 Send confirmation email
and
order->>notify: 📱 Send push notification
end
order-->>gw: ✅ Order confirmed
gw-->>browser: ✅ Show confirmation page
else ❌ Inventory unavailable
order->>payment: 🔄 Void authorization
order-->>gw: ⚠️ Items out of stock
gw-->>browser: ⚠️ Show stock error
else ❌ Payment declined
order->>inventory: 🔄 Release reservation
loop 🔄 Retry up to 2 times
order->>payment: 💰 Retry authorization
payment-->>order: ❌ Still declined
end
order-->>gw: ❌ Payment failed
gw-->>browser: ❌ Show payment error
end
```
### Why this works
- **`box` grouping** clusters participants by architectural layer — readers instantly see which services are client-facing vs backend
- **`par` blocks** show parallel inventory + payment checks happening simultaneously, which is how real checkout systems work for performance
- **Nested `alt`/`else`** covers the happy path AND two distinct failure modes, each with proper cleanup (void auth, release reservation)
- **`loop` for retry logic** shows the payment retry pattern without cluttering the happy path
- **Emoji in messages** makes scanning fast — 📦 for inventory, 💰 for payment, ✅/❌ for outcomes

150
scientific-skills/markdown-mermaid-writing/references/diagrams/state.md Normal file
View File

@@ -0,0 +1,150 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# State Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `stateDiagram-v2`
**Best for:** State machines, lifecycle flows, status transitions, object lifecycles
**When NOT to use:** Sequential processes with many steps (use [Flowchart](flowchart.md)), timing-critical interactions (use [Sequence](sequence.md))
---
## Exemplar Diagram
```mermaid
stateDiagram-v2
accTitle: Order Fulfillment Lifecycle
accDescr: State machine for an e-commerce order from placement through payment, fulfillment, and delivery with cancellation paths
[*] --> Placed: 📋 Customer submits
Placed --> PaymentPending: 💰 Initiate payment
PaymentPending --> PaymentFailed: ❌ Declined
PaymentPending --> Confirmed: ✅ Payment received
PaymentFailed --> Placed: 🔄 Retry payment
PaymentFailed --> Cancelled: 🚫 Customer cancels
Confirmed --> Picking: 📦 Warehouse picks
Picking --> Shipped: 🚚 Carrier collected
Shipped --> Delivered: ✅ Proof of delivery
Delivered --> [*]: 🏁 Complete
Cancelled --> [*]: 🏁 Closed
note right of Confirmed
📋 Inventory reserved
💰 Invoice generated
end note
```
---
## Tips
- Always start with `[*]` (initial state) and end with `[*]` (terminal)
- Label transitions with **emoji + action** for visual clarity
- Use `note right of` / `note left of` for contextual details
- State names: `CamelCase` (Mermaid convention for state diagrams)
- Use nested states sparingly: `state "name" as s1 { ... }`
- Keep to **8–10 states** maximum
---
## Template
```mermaid
stateDiagram-v2
accTitle: Your Title Here
accDescr: Describe the entity lifecycle and key transitions between states
[*] --> InitialState: ⚡ Trigger event
InitialState --> ActiveState: ▶️ Action taken
ActiveState --> CompleteState: ✅ Success
ActiveState --> FailedState: ❌ Error
CompleteState --> [*]: 🏁 Done
FailedState --> [*]: 🏁 Closed
```
---
## Complex Example
A CI/CD pipeline modeled as a state machine with 3 composite (nested) states, each containing internal substates. Shows how source changes flow through build, test, and deploy phases with failure recovery and rollback transitions.
```mermaid
stateDiagram-v2
accTitle: CI/CD Pipeline State Machine
accDescr: Composite state diagram for a CI/CD pipeline showing source detection, build and test phases with parallel scanning, and a three-stage deployment with approval gate and rollback path
[*] --> Source: ⚡ Commit pushed
state "📥 Source" as Source {
[*] --> Idle
Idle --> Fetching: 🔄 Poll detected change
Fetching --> Validating: 📋 Checkout complete
Validating --> [*]: ✅ Config valid
}
Source --> Build: ⚙️ Pipeline triggered
state "🔧 Build & Test" as Build {
[*] --> Compiling
Compiling --> UnitTests: ✅ Build artifact ready
UnitTests --> IntegrationTests: ✅ Unit tests pass
IntegrationTests --> SecurityScan: ✅ Integration pass
SecurityScan --> [*]: ✅ No vulnerabilities
note right of Compiling
📦 Docker image built
🏷️ Tagged with commit SHA
end note
}
Build --> Deploy: 📦 Artifact published
Build --> Failed: ❌ Build or test failure
state "🚀 Deployment" as Deploy {
[*] --> Staging
Staging --> WaitApproval: ✅ Staging healthy
WaitApproval --> Production: ✅ Approved
WaitApproval --> Cancelled: 🚫 Rejected
Production --> Monitoring: 🚀 Deployed
Monitoring --> [*]: ✅ Stable 30 min
note right of WaitApproval
👤 Requires team lead approval
⏰ Auto-reject after 24h
end note
}
Deploy --> Rollback: ❌ Health check failed
Rollback --> Deploy: 🔄 Revert to previous
Deploy --> Complete: 🏁 Pipeline finished
Failed --> Source: 🔧 Fix pushed
Cancelled --> [*]: 🏁 Pipeline aborted
Complete --> [*]: 🏁 Done
state Failed {
[*] --> AnalyzeFailure
AnalyzeFailure --> NotifyTeam: 📤 Alert sent
NotifyTeam --> [*]
}
state Rollback {
[*] --> RevertArtifact
RevertArtifact --> RestorePrevious: 🔄 Previous version
RestorePrevious --> VerifyRollback: 🔍 Health check
VerifyRollback --> [*]
}
```
### Why this works
- **Composite states group pipeline phases** — Source, Build & Test, and Deployment each contain their internal flow, readable in isolation or as part of the whole
- **Failure and rollback are first-class states** — not just transition labels. The Failed and Rollback states have their own internal substates showing what actually happens during recovery
- **Notes on key states** add operational context — the approval gate has timeout rules, the compile step documents the artifact format. This is the kind of detail operators need.
- **Transitions between composite states** are the high-level flow (Source → Build → Deploy → Complete), while transitions within composites are the detailed steps. Two levels of reading for two audiences.

96
scientific-skills/markdown-mermaid-writing/references/diagrams/timeline.md Normal file
View File

@@ -0,0 +1,96 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Timeline
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `timeline`
**Best for:** Chronological events, historical progression, milestones over time, release history
**When NOT to use:** Task durations/dependencies (use [Gantt](gantt.md)), detailed project plans (use [Gantt](gantt.md))
> ⚠️ **Accessibility:** Timelines do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_Timeline of a startup's growth milestones from founding through Series A, organized by year and quarter:_
```mermaid
timeline
title 🚀 Startup Growth Milestones
section 2024
Q1 : 💡 Founded : Built MVP
Q2 : 🧪 Beta launch : 100 users
Q3 : 📈 Product-market fit : 1K users
Q4 : 💰 Seed round : $2M raised
section 2025
Q1 : 👥 Team of 10 : Hired engineering lead
Q2 : 🌐 Public launch : 10K users
Q3 : 🏢 Enterprise tier : First B2B deal
Q4 : 📊 $1M ARR : Series A prep
section 2026
Q1 : 🚀 Series A : $15M raised
```
---
## Tips
- Use `section` to group by year, quarter, or phase
- Each entry can have multiple items separated by `:`
- Keep items concise — 2–4 words each
- Emoji at the start of key items for visual anchoring
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of the timeline and the period it covers:_
```mermaid
timeline
title 📋 Your Timeline Title
section Period 1
Event A : Detail one : Detail two
Event B : Detail three
section Period 2
Event C : Detail four
Event D : Detail five : Detail six
```
---
## Complex Example
_Multi-year technology platform evolution tracking a startup's journey from monolith through microservices to AI-powered platform. Six sections span 2020-2025, each capturing key technical milestones and business metrics that drove architecture decisions:_
```mermaid
timeline
title 🚀 Platform Architecture Evolution
section 2020 — Monolith Era
Q1 : 💡 Founded company : Rails monolith launched : 10 engineers
Q3 : ⚠️ Hit scaling ceiling : 50K concurrent users : Database bottleneck
section 2021 — Breaking Apart
Q1 : 🔐 Extracted auth service : 🐳 Adopted Docker : CI/CD pipeline live
Q3 : 📦 Split order processing : ⚡ Added Redis cache : 200K users
section 2022 — Microservices
Q1 : ⚙️ 8 services in production : ☸️ Kubernetes migration : Service mesh pilot
Q3 : 📥 Event-driven architecture : 📊 Observability stack : 500K users
section 2023 — Platform Maturity
Q1 : 🌐 Multi-region deployment : 🛡️ Zero-trust networking : 50 engineers
Q3 : 🔄 Canary deployments : 📈 99.99% uptime SLA : 2M users
section 2024 — AI Integration
Q1 : 🧠 ML recommendation engine : ⚡ Real-time personalization
Q3 : 🔍 AI-powered search : 📊 Predictive analytics : 5M users
section 2025 — Next Generation
Q1 : ☁️ Edge computing rollout : 🤖 AI agent platform : 10M users
```
### Why this works
- **6 sections are eras, not just years** — "Monolith Era", "Breaking Apart", "Microservices" tell the story of _why_ the architecture changed, not just _when_
- **Business metrics alongside tech milestones** — user counts and team size appear next to architecture decisions. This shows the _pressure_ that drove each evolution (50K users → scaling ceiling → extracted services)
- **Multiple items per time point** — each quarter packs 2-3 items separated by `:`, giving a dense but scannable view of everything happening in parallel
- **Emoji anchors the scan** — eyes land on 🧠 ML, 🌐 Multi-region, ⚡ Redis before reading the text. For a quick skim, the emoji alone tells the story

66
scientific-skills/markdown-mermaid-writing/references/diagrams/treemap.md Normal file
View File

@@ -0,0 +1,66 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# Treemap Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `treemap-beta`
**Mermaid version:** v11.12.0+
**Best for:** Hierarchical data proportions, budget breakdowns, disk usage, portfolio composition
**When NOT to use:** Simple flat proportions (use [Pie](pie.md)), flow-based hierarchy (use [Sankey](sankey.md))
> ⚠️ **Accessibility:** Treemap diagrams do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
>
> ⚠️ **GitHub support:** Treemap is very new — verify it renders on your target GitHub version before using.
---
## Exemplar Diagram
_Treemap showing annual cloud infrastructure costs broken down by service category and specific service, with rectangle sizes proportional to spend:_
```mermaid
treemap-beta
"Compute"
"EC2 Instances": 45000
"Lambda Functions": 12000
"ECS Containers": 8000
"Storage"
"S3 Buckets": 18000
"RDS Databases": 15000
"DynamoDB": 6000
"Networking"
"CloudFront CDN": 9000
"API Gateway": 7000
"Observability"
"CloudWatch": 5000
"Datadog": 8000
```
---
## Tips
- Parent nodes (sections) use quoted text: `"Section Name"`
- Leaf nodes add a value: `"Leaf Name": 123`
- Hierarchy is created by **indentation** (spaces or tabs)
- Values determine the size of each rectangle — larger value = larger area
- Keep to **2–3 levels** of nesting for clarity
- Use `classDef` and `:::class` syntax for styling nodes
- **Always** pair with a Markdown text description above for screen readers
---
## Template
_Description of the hierarchical data and what the proportions represent:_
```mermaid
treemap-beta
"Category A"
"Sub A1": 40
"Sub A2": 25
"Category B"
"Sub B1": 20
"Sub B2": 15
```

108
scientific-skills/markdown-mermaid-writing/references/diagrams/user_journey.md Normal file
View File

@@ -0,0 +1,108 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# User Journey
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `journey`
**Best for:** User experience mapping, customer journey, process satisfaction scoring, onboarding flows
**When NOT to use:** Simple processes without satisfaction data (use [Flowchart](flowchart.md)), chronological events (use [Timeline](timeline.md))
---
## Exemplar Diagram
```mermaid
journey
accTitle: New Developer Onboarding Experience
accDescr: Journey map tracking a new developer through day-one setup, first-week integration, and month-one productivity with satisfaction scores at each step
title 👤 New Developer Onboarding
section 📋 Day 1 Setup
Read onboarding doc : 3 : New Dev
Clone repositories : 4 : New Dev
Configure local env : 2 : New Dev
Run into setup issues : 1 : New Dev
section 🤝 Week 1 Integration
Meet the team : 5 : New Dev
Pair program on first PR : 4 : New Dev, Mentor
Navigate codebase : 2 : New Dev
First PR merged : 5 : New Dev
section 🚀 Month 1 Productivity
Own a small feature : 4 : New Dev
Participate in code review: 4 : New Dev
Ship to production : 5 : New Dev
```
---
## Tips
- Scores: **1** = 😤 frustrated, **3** = 😐 neutral, **5** = 😄 delighted
- Assign actors after the score: `5 : Actor1, Actor2`
- Use `section` with **emoji prefix** to group by time period or phase
- Focus on **pain points** (low scores) — that's where the insight is
- Keep to **3–4 sections** with **3–4 steps** each
---
## Template
```mermaid
journey
accTitle: Your Title Here
accDescr: Describe the user journey and what experience insights it reveals
title 👤 Journey Title
section 📋 Phase 1
Step one : 3 : Actor
Step two : 4 : Actor
section 🔧 Phase 2
Step three : 2 : Actor
Step four : 5 : Actor
```
---
## Complex Example
A multi-persona e-commerce journey comparing a New Customer vs Returning Customer across 5 phases. The two actors experience the same flow with different satisfaction scores, revealing exactly where first-time UX needs investment.
```mermaid
journey
accTitle: E-Commerce Customer Journey Comparison
accDescr: Side-by-side journey map comparing new customer and returning customer satisfaction across discovery, shopping, checkout, fulfillment, and post-purchase phases to identify first-time experience gaps
title 👤 E-Commerce Customer Journey Comparison
section 🔍 Discovery
Find the product : 3 : New Customer, Returning Customer
Read reviews : 4 : New Customer, Returning Customer
Compare alternatives : 3 : New Customer
Go to saved favorite : 5 : Returning Customer
section 🛒 Shopping
Add to cart : 4 : New Customer, Returning Customer
Apply coupon code : 2 : New Customer
Use stored coupon : 5 : Returning Customer
Choose shipping option : 3 : New Customer, Returning Customer
section 💰 Checkout
Enter payment details : 2 : New Customer
Use saved payment : 5 : Returning Customer
Review and confirm : 4 : New Customer, Returning Customer
Receive confirmation : 5 : New Customer, Returning Customer
section 📦 Fulfillment
Track shipment : 3 : New Customer, Returning Customer
Receive delivery : 5 : New Customer, Returning Customer
Unbox product : 5 : New Customer, Returning Customer
section 🔄 Post-Purchase
Leave a review : 2 : New Customer
Contact support : 1 : New Customer
Reorder same item : 5 : Returning Customer
Recommend to friend : 3 : Returning Customer
```
### Why this works
- **Two personas on the same map** — instead of two separate diagrams, both actors appear in each step. The satisfaction gap between New Customer (2-3) and Returning Customer (4-5) is immediately visible in checkout and post-purchase.
- **5 sections follow the real funnel** — discovery → shopping → checkout → fulfillment → post-purchase. Each section tells a story about where the experience breaks down for new users.
- **Some steps are persona-specific** — "Compare alternatives" is only New Customer, "Reorder same item" is only Returning Customer. This shows divergent paths within the shared journey.
- **Low scores are the actionable insight** — New Customer scores 1-2 on payment entry, coupon application, and support contact. These are the specific UX investments that would improve conversion.

53
scientific-skills/markdown-mermaid-writing/references/diagrams/xy_chart.md Normal file
View File

@@ -0,0 +1,53 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# XY Chart
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `xychart-beta`
**Best for:** Numeric data visualization, trends over time, bar/line comparisons, metric dashboards
**When NOT to use:** Proportional breakdowns (use [Pie](pie.md)), qualitative comparisons (use [Quadrant](quadrant.md))
> ⚠️ **Accessibility:** XY charts do **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_XY chart comparing monthly revenue growth (bars) versus customer acquisition cost (line) over six months, showing improving unit economics as revenue rises while CAC steadily decreases:_
```mermaid
xychart-beta
title "📈 Revenue vs Customer Acquisition Cost"
x-axis [Jan, Feb, Mar, Apr, May, Jun]
y-axis "Thousands ($)" 0 --> 120
bar [20, 35, 48, 62, 78, 95]
line [50, 48, 45, 40, 35, 30]
```
---
## Tips
- Combine `bar` and `line` to show different metrics on the same chart
- Use **emoji in the title** for visual flair: `"📈 Revenue Growth"`
- Use quoted `title` and axis labels
- Define axis range with `min --> max`
- Keep data points to **6–12** for readability
- Multiple `bar` or `line` entries create grouped series
- **Always** pair with a detailed Markdown text description above for screen readers
---
## Template
_Description of what the X axis, Y axis, bars, and lines represent and the key insight:_
```mermaid
xychart-beta
title "📊 Your Chart Title"
x-axis [Label1, Label2, Label3, Label4]
y-axis "Unit" 0 --> 100
bar [25, 50, 75, 60]
line [30, 45, 70, 55]
```

71
scientific-skills/markdown-mermaid-writing/references/diagrams/zenuml.md Normal file
View File

@@ -0,0 +1,71 @@
<!-- Source: https://github.com/borealBytes/opencode | License: Apache-2.0 | Author: Clayton Young / Superior Byte Works, LLC (Boreal Bytes) -->
# ZenUML Sequence Diagram
> **Back to [Style Guide](../mermaid_style_guide.md)** — Read the style guide first for emoji, color, and accessibility rules.
**Syntax keyword:** `zenuml`
**Best for:** Code-like sequence diagrams, method-call-style interactions, developers familiar with programming syntax
**When NOT to use:** Prefer standard [Sequence Diagrams](sequence.md) for most use cases — ZenUML requires an external plugin and has limited GitHub support.
> ⚠️ **GitHub support:** ZenUML requires the `@mermaid-js/mermaid-zenuml` external module. It may **not render** on GitHub natively. Use standard `sequenceDiagram` syntax for GitHub compatibility.
>
> ⚠️ **Accessibility:** ZenUML does **not** support `accTitle`/`accDescr`. Always place a descriptive _italic_ Markdown paragraph directly above the code block.
---
## Exemplar Diagram
_ZenUML sequence diagram showing a user authentication flow with credential validation and token generation using programming-style syntax:_
```mermaid
zenuml
@Actor User
@Boundary AuthAPI
@Entity Database
// User initiates login
User->AuthAPI.login(credentials) {
AuthAPI->Database.findUser(email) {
return user
}
if (user.valid) {
return token
} else {
return error
}
}
```
---
## Tips
- Uses **programming-style syntax** with method calls: `A->B.method(args)`
- Curly braces `{}` create natural nesting (activation bars)
- Control flow: `if/else`, `while`, `for`, `try/catch/finally`, `par`
- Participant types: `@Actor`, `@Boundary`, `@Entity`, `@Database`, `@Control`
- Comments with `//` render above messages
- `return` keyword draws return arrows
- **Prefer standard `sequenceDiagram`** for GitHub compatibility
- Use ZenUML only when the code-style syntax is specifically desired
---
## Template
_Description of the interaction flow:_
```mermaid
zenuml
@Actor User
@Boundary Server
@Entity DB
User->Server.request(data) {
Server->DB.query(params) {
return results
}
return response
}
```