@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/content/mermaid/SKILL.md

@@ -0,0 +1,635 @@
+---
+name: mermaid
+description: Create and edit Mermaid diagrams for architecture, API flows, database schemas, workflows, and data models.
+user-invocable: true
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Mermaid Diagram Creation
+Create clear, professional Mermaid diagrams.
+
+## Critical Rules
+
+### Mandatory Validation
+**BEFORE reporting task completion, you MUST:**
+1. Verify the diagram syntax is valid
+2. Test rendering at mermaid.live if creating complex diagrams
+3. Verify node IDs are alphanumeric (no special chars except underscore)
+4. Only report success after confirming the diagram renders without errors
+
+### Text Escaping Rules
+**Escaping is NOT always required.** Only escape when a character breaks Mermaid syntax.
+
+**Node IDs (no escaping needed):**
+- Use camelCase or snake_case: `userService`, `api_gateway`
+- Alphanumeric only, start with letter: `node1`, `stepA`
+- No spaces, no special characters except underscore
+
+**Node Labels - Most characters work without escaping:**
+- **No escaping needed:** `A[User Login]`, `B[Process Data]`, `C[version 1.0]`, `D[status: ok]`
+- **Use quotes when syntax conflicts:** `A["This has (parens)"]`, `B["Text with [brackets]"]`
+
+**Characters that WILL break syntax (must handle):**
+| Character | When it breaks | Solution |
+|-----------|----------------|----------|
+| `()` parens | In node labels `A[text (here)]` | Quote: `A["text (here)"]` or entity: `#lpar;` `#rpar;` |
+| `[]` brackets | In node labels | Quote: `A["text [here]"]` |
+| `{}` braces | In node labels | Quote: `A["text {here}"]` or entity: `#lcub;` `#rcub;` |
+| `"` quotes | Inside quoted labels | Escape: `A["He said \"hello\""]` or entity: `#quot;` |
+| `;` semicolon | In sequence diagrams (line delimiter) | Entity: `#59;` |
+| `#` hash | Conflicts with entity syntax | Entity: `#35;` or quote the label |
+
+**Characters that usually work fine (escape only if broken):**
+- `.` dots: `A[file.txt]` ✓
+- `/` slashes: `A[POST /api/users]` ✓
+- `:` colons: `A[Status: Active]` ✓
+- `-` dashes: `A[User-Service]` ✓
+- `&` ampersand: Usually works, use `#amp;` if issues
+- `%` percent: Usually works, use `#37;` if issues
+- `<>` angle brackets: Usually works, use `#lt;` `#gt;` if issues
+
+**Preferred approach: Use double quotes**
+```mermaid
+flowchart TD
+    A["POST /api/users"] --> B["Status: 200"]
+    B --> C["Config (optional)"]
+```
+
+**Alternative: HTML Entity Codes**
+- `#lpar;` `#rpar;` for `(` `)`
+- `#lcub;` `#rcub;` for `{` `}`
+- `#quot;` for `"`
+- `#59;` for `;` (required in sequence diagrams)
+- `#35;` for `#`
+- `#amp;` for `&`
+- `#lt;` `#gt;` for `<` `>`
+
+**Examples:**
+
+```mermaid
+flowchart TD
+    %% These work WITHOUT escaping
+    A[POST /api/login] --> B[Validate Credentials]
+    B -->|status: 200| C[Generate JWT]
+    C --> D[Return Token]
+
+    %% File paths and versions - no escaping needed
+    E[config.json] --> F[version 2.1.0]
+
+    %% Parentheses NEED quotes or entity codes
+    G["User (admin)"] --> H["Role (superuser)"]
+
+    %% Brackets NEED quotes
+    I["Array[String]"] --> J["Map[K, V]"]
+```
+
+```mermaid
+sequenceDiagram
+    %% Most characters work fine
+    User->>API: POST /auth/login
+    API->>DB: SELECT * FROM users
+    DB-->>API: User found
+
+    %% Semicolons MUST be escaped in sequence diagrams
+    API->>Log: Event#59; user_login
+
+    %% Parentheses need quotes
+    User->>API: "Get config (optional)"
+```
+
+**Relationship Labels in ER Diagrams:**
+```mermaid
+erDiagram
+    %% Always quote relationship text
+    USER ||--o{ ORDER : "places order"
+    ORDER }o--|| PRODUCT : "contains item"
+```
+
+### Pre-Delivery Checklist
+Before reporting any mermaid diagram task as complete:
+- [ ] Parentheses `()` in labels: quoted or escaped with `#lpar;` `#rpar;`
+- [ ] Brackets `[]` in labels: quoted
+- [ ] Braces `{}` in labels: quoted or escaped with `#lcub;` `#rcub;`
+- [ ] Semicolons in sequence diagrams: escaped with `#59;`
+- [ ] Hash `#` if present: escaped with `#35;`
+- [ ] ER relationships are quoted: `: "places order"`
+- [ ] Syntax validated (no missing brackets/arrows)
+- [ ] Complex diagrams tested at mermaid.live
+- [ ] Diagram renders without errors
+
+**Note:** Most other characters (dots, slashes, colons, dashes) do NOT need escaping.
+
+## When to Use
+
+- System architecture diagrams
+- API and sequence flows
+- Database schemas and ER diagrams
+- Process workflows and state machines
+- Git branching strategies
+- Class hierarchies and relationships
+- Gantt charts and timelines
+
+## Diagram Types
+
+### Flowchart
+Use for: Process flows, decision trees, algorithm visualization
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Input[/Get User Input/]
+    Input --> Validate{Valid?}
+    Validate -->|Yes| Process["Process Data"]
+    Validate -->|No| Error["Show Error"]
+    Error --> Input
+    Process --> Save[(Save to DB)]
+    Save --> End([End])
+```
+
+**Key syntax:**
+- `TD` = Top Down, `LR` = Left Right, `RL` = Right Left, `BT` = Bottom Top
+- `[Rectangle]`, `(Rounded)`, `{Diamond}`, `[(Database)]`, `([Stadium])`
+- `-->` solid line, `-.->` dotted line, `==>` thick line
+- `-->|Label|` for labeled edges
+
+### Graph (Legacy Syntax)
+Use for: Same as flowchart, but with older syntax (still widely supported)
+
+```mermaid
+graph TD
+    A[Start] --> B["Check Input"]
+    B -->|Valid| C["Process"]
+    B -->|Invalid| D["Error"]
+    D --> B
+    C --> E[End]
+```
+
+**Flowchart vs Graph:**
+| Feature | `flowchart` | `graph` |
+|---------|-------------|---------|
+| Syntax | Newer (v8.6.0+) | Legacy |
+| Features | More node shapes, better styling | Basic features |
+| Recommendation | **Preferred** for new diagrams | Use for compatibility |
+| Support | Modern Mermaid versions | All versions |
+
+**When to use `graph` instead of `flowchart`:**
+- Working with older Mermaid versions (pre-v8.6)
+- Existing codebase uses `graph` syntax
+- Maximum compatibility required
+
+**Prefer `flowchart` for:**
+- New diagrams
+- Advanced node shapes
+- Better layout control
+- Modern documentation
+
+### Sequence Diagram
+Use for: API interactions, authentication flows, message passing
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant Frontend
+    participant API
+    participant DB
+
+    User->>Frontend: Click Login
+    Frontend->>API: POST /auth/login
+    activate API
+    API->>DB: Query user
+    DB-->>API: User data
+    API->>API: Verify password
+    API-->>Frontend: JWT token
+    deactivate API
+    Frontend->>User: Redirect to dashboard
+```
+
+**Key syntax:**
+- `->>` solid arrow, `-->>` dotted arrow (response)
+- `activate`/`deactivate` for lifelines
+- `Note over A,B: Text` for annotations
+- `actor` for human users, `participant` for systems
+
+### Class Diagram
+Use for: Object-oriented design, data structures, type hierarchies
+
+```mermaid
+classDiagram
+    class User {
+        +String id
+        +String email
+        +String name
+        -String passwordHash
+        +login() bool
+        +updateProfile() void
+    }
+
+    class Post {
+        +String id
+        +String title
+        +String content
+        +DateTime createdAt
+        +publish() void
+    }
+
+    class Comment {
+        +String id
+        +String text
+        +DateTime createdAt
+    }
+
+    User "1" --> "*" Post : creates
+    Post "1" --> "*" Comment : has
+    User "1" --> "*" Comment : writes
+```
+
+**Key syntax:**
+- `+` public, `-` private, `#` protected
+- `"1"` to `"*"` for cardinality
+- `<|--` inheritance, `*--` composition, `o--` aggregation
+- `-->` association, `..>` dependency
+
+### Entity Relationship Diagram
+Use for: Database schema design, data modeling
+
+```mermaid
+erDiagram
+    USER ||--o{ POST : creates
+    USER ||--o{ COMMENT : writes
+    POST ||--o{ COMMENT : has
+    POST }o--|| CATEGORY : "belongs to"
+
+    USER {
+        uuid id PK
+        string email UK
+        string name
+        timestamp created_at
+    }
+
+    POST {
+        uuid id PK
+        uuid user_id FK
+        uuid category_id FK
+        string title
+        text content
+        timestamp published_at
+    }
+
+    COMMENT {
+        uuid id PK
+        uuid user_id FK
+        uuid post_id FK
+        text content
+    }
+
+    CATEGORY {
+        uuid id PK
+        string name UK
+    }
+```
+
+**Key syntax:**
+- `||--o{` one to many
+- `||--||` one to one
+- `}o--o{` many to many
+- `PK` primary key, `FK` foreign key, `UK` unique key
+
+### State Diagram
+Use for: State machines, workflow stages, lifecycle management
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Review : Submit
+    Review --> Approved : Approve
+    Review --> Rejected : Reject
+    Review --> Draft : Request Changes
+    Rejected --> Draft : Revise
+    Approved --> Published : Publish
+    Published --> Archived : Archive
+    Archived --> [*]
+
+    state Review {
+        [*] --> PendingReview
+        PendingReview --> InReview : Assign Reviewer
+        InReview --> [*]
+    }
+```
+
+### Git Graph
+Use for: Git branching strategies, release workflows
+
+```mermaid
+gitGraph
+    commit id: "Initial commit"
+    branch develop
+    checkout develop
+    commit id: "Add feature A"
+    branch feature/login
+    checkout feature/login
+    commit id: "Implement auth"
+    commit id: "Add tests"
+    checkout develop
+    merge feature/login
+    checkout main
+    merge develop tag: "v1.0.0"
+    checkout develop
+    commit id: "Add feature B"
+```
+
+### Timeline / Gantt
+Use for: Project planning, milestone tracking
+
+```mermaid
+gantt
+    title Project Timeline
+    dateFormat YYYY-MM-DD
+    section Planning
+        Requirements     :done, req, 2024-01-01, 2024-01-15
+        Design          :done, des, 2024-01-10, 2024-01-25
+    section Development
+        Backend API     :active, dev1, 2024-01-20, 2024-02-15
+        Frontend        :dev2, after dev1, 20d
+    section Testing
+        QA Testing      :test, after dev2, 10d
+    section Deployment
+        Deploy to Prod  :milestone, after test, 0d
+```
+
+## Best Practices
+
+### Clarity
+- Keep diagrams focused on one concept
+- Use consistent naming conventions
+- Limit nodes to 10-15 per diagram
+- Break complex diagrams into multiple views
+
+### Styling
+```mermaid
+flowchart LR
+    A[Normal] --> B[Process]
+    B --> C[Result]
+
+    classDef important fill:#ff6b6b,stroke:#c92a2a,color:#fff
+    classDef success fill:#51cf66,stroke:#2b8a3e,color:#fff
+
+    class B important
+    class C success
+```
+
+### Subgraphs for Grouping
+```mermaid
+flowchart TB
+    subgraph Frontend
+        UI[React App]
+        State[Redux Store]
+    end
+
+    subgraph Backend
+        API[FastAPI]
+        DB[(PostgreSQL)]
+    end
+
+    UI --> API
+    API --> DB
+```
+
+### Links and Tooltips
+```mermaid
+flowchart LR
+    A[Click Me] --> B[With Tooltip]
+    click A "https://example.com" "Link to docs"
+    B:::tooltip
+```
+
+## Common Patterns
+
+### Microservices Architecture
+```mermaid
+flowchart TB
+    Client[Client App]
+    Gateway[API Gateway]
+
+    subgraph Services
+        Auth[Auth Service]
+        Users[User Service]
+        Orders[Order Service]
+    end
+
+    subgraph Data
+        AuthDB[(Auth DB)]
+        UserDB[(User DB)]
+        OrderDB[(Order DB)]
+    end
+
+    Client --> Gateway
+    Gateway --> Auth
+    Gateway --> Users
+    Gateway --> Orders
+
+    Auth --> AuthDB
+    Users --> UserDB
+    Orders --> OrderDB
+```
+
+### API Request Flow
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant LB as Load Balancer
+    participant API as API Server
+    participant Cache as Redis
+    participant DB as Database
+
+    C->>LB: HTTPS Request
+    LB->>API: Forward Request
+    API->>Cache: Check Cache
+    alt Cache Hit
+        Cache-->>API: Return Data
+    else Cache Miss
+        API->>DB: Query Data
+        DB-->>API: Result
+        API->>Cache: Store in Cache
+    end
+    API-->>LB: Response
+    LB-->>C: Return Response
+```
+
+### Database Schema
+```mermaid
+erDiagram
+    USERS ||--o{ ORDERS : places
+    USERS ||--o{ ADDRESSES : has
+    ORDERS ||--|{ ORDER_ITEMS : contains
+    ORDERS }o--|| ADDRESSES : "ships to"
+    PRODUCTS ||--o{ ORDER_ITEMS : "ordered in"
+
+    USERS {
+        uuid id PK
+        string email UK
+        timestamp created_at
+    }
+
+    ORDERS {
+        uuid id PK
+        uuid user_id FK
+        uuid shipping_address_id FK
+        enum status
+        decimal total
+    }
+```
+
+## Rendering
+
+Mermaid diagrams can be rendered:
+- GitHub/GitLab markdown (native support)
+- VSCode with Mermaid extensions
+- Documentation tools (MkDocs, Docusaurus)
+- Online: mermaid.live
+- Export to SVG/PNG for presentations
+
+## Validation Workflow
+
+**MANDATORY before reporting completion:**
+
+1. **Syntax Check**
+   - Verify all node IDs are valid (alphanumeric, start with letter)
+   - Check all special characters are quoted
+   - Confirm arrow syntax is correct (`-->`, `->>`, `-->>`, etc.)
+
+2. **Rendering Test**
+   - For simple diagrams: Visual review of syntax
+   - For complex diagrams: Test at mermaid.live
+   - Paste diagram into mermaid.live editor
+   - Confirm it renders without errors
+   - Check for warnings in console
+
+3. **Content Validation**
+   - All labels display correctly
+   - All relationships are visible
+   - Layout is clear and readable
+   - No overlapping nodes or text
+
+4. **Common Failure Points to Check**
+   - [ ] Parentheses `()` in labels: quoted or use `#lpar;` `#rpar;`
+   - [ ] Brackets `[]` in labels: quoted
+   - [ ] Braces `{}` in labels: quoted or use `#lcub;` `#rcub;`
+   - [ ] Semicolons `;` in sequence diagrams: use `#59;`
+   - [ ] Hash `#` conflicts with entity syntax: use `#35;`
+   - [ ] Quotes `"` inside quoted labels: use `\"` or `#quot;`
+   - [ ] ER diagram relationships are quoted: `: "places order"`
+   - [ ] No syntax errors (missing brackets, wrong arrows)
+
+   **Note:** Dots, slashes, colons, dashes usually work fine without escaping.
+
+**Only after all checks pass should you report task completion.**
+
+## Troubleshooting
+
+### Common Issues and Fixes
+
+1. **Syntax errors: "Parse error on line X"**
+   - **Cause**: Missing quotes, wrong brackets, invalid arrows
+   - **Fix**: Check quotes around special characters, verify bracket pairs
+   - **Example**: `A[POST /users]` → `A["POST /users"]`
+
+2. **Graph too complex / layout issues**
+   - **Cause**: Too many nodes, unclear relationships
+   - **Fix**: Split into multiple diagrams, use subgraphs
+   - **Limit**: Keep under 15 nodes per diagram
+
+3. **Labels not showing / cut off**
+   - **Cause**: Missing quotes on multi-word labels
+   - **Fix**: Add quotes around labels with spaces or special chars
+   - **Example**: `A -->|status 200| B` → `A -->|"status 200"| B`
+
+4. **Wrong direction / poor layout**
+   - **Cause**: Incorrect orientation setting
+   - **Fix**: Use `TD` (top-down), `LR` (left-right), `RL`, `BT`
+   - **Tip**: Try different orientations for better readability
+
+5. **Special characters breaking diagram**
+   - **Cause**: Syntax-breaking characters (parentheses, brackets, braces, semicolons)
+   - **Fix**: Quote the label or use HTML entity codes
+   - **Example**: `A[Init (optional)]` → `A["Init (optional)"]` or `A[Init #lpar;optional#rpar;]`
+   - **Example**: `B[Array[String]]` → `B["Array[String]"]`
+   - **Example**: `C[Map{K,V}]` → `C["Map{K,V}"]` or `C[Map#lcub;K,V#rcub;]`
+   - **Example**: `D[User "admin"]` → `D["User \"admin\""]` or `D[User #quot;admin#quot;]`
+   - **Note**: Dots, slashes, colons usually work fine: `A[file.txt]` ✓, `B[POST /api]` ✓
+
+6. **Relationships not rendering in ER diagrams**
+   - **Cause**: Unquoted relationship labels
+   - **Fix**: Always quote relationship text
+   - **Example**: `A ||--o{ B : places` → `A ||--o{ B : "places"`
+
+### Validation Tips
+- **Always test** complex diagrams at mermaid.live before delivery
+- **Use comments** to document: `%% This is a comment`
+- **Check quotes** around any text with spaces or special chars
+- **Verify syntax** against examples in this guide
+- **Test rendering** in target platform (GitHub, GitLab, docs site)
+- **Version check**: Mermaid version affects available features
+
+## Quick Reference
+
+| Diagram Type | Use Case | Syntax Start |
+|-------------|----------|--------------|
+| Flowchart | Processes, algorithms (preferred) | `flowchart TD` |
+| Graph | Processes, algorithms (legacy) | `graph TD` |
+| Sequence | API flows, interactions | `sequenceDiagram` |
+| Class | OOP design, types | `classDiagram` |
+| ER | Database schema | `erDiagram` |
+| State | State machines | `stateDiagram-v2` |
+| Git | Version control | `gitGraph` |
+| Gantt | Timelines | `gantt` |
+| Pie | Data distribution | `pie title Text` |
+| Journey | User flows | `journey` |
+
+**Remember - Only escape when syntax breaks:**
+
+**Must handle (will break syntax):**
+- **Parentheses** `()`: Quote `["Init (optional)"]` or `#lpar;` `#rpar;`
+- **Brackets** `[]`: Quote `["Array[String]"]`
+- **Braces** `{}`: Quote `["Map{K,V}"]` or `#lcub;` `#rcub;`
+- **Semicolons** `;` in sequence diagrams: `#59;`
+- **Hash** `#`: `#35;` (conflicts with entity syntax)
+- **Quotes** `"` inside quoted labels: `\"` or `#quot;`
+
+**Usually work fine (no escaping needed):**
+- Dots: `A[file.txt]` ✓
+- Slashes: `A[POST /api/users]` ✓
+- Colons: `A[Status: Active]` ✓
+- Dashes: `A[User-Service]` ✓
+
+**Preferred approach:** Use double quotes for labels with special characters
+- Test complex diagrams at mermaid.live before delivery
+
+## Examples by Context
+
+### Authentication Flow
+```mermaid
+sequenceDiagram
+    User->>App: Enter credentials
+    App->>API: POST /login
+    API->>DB: Verify user
+    DB-->>API: User found
+    API->>API: Generate JWT
+    API-->>App: Return token
+    App->>App: Store in localStorage
+    App->>User: Redirect to dashboard
+
+    Note over API,DB: Uses bcrypt v4.1.2
+```
+
+### Deployment Pipeline
+```mermaid
+flowchart LR
+    Dev["Developer Push"] --> GH[GitHub]
+    GH --> CI{"CI Pipeline"}
+    CI -->|"Tests Pass"| Build["Build Image"]
+    CI -->|"Tests Fail"| Notify["Notify Team"]
+    Build --> Push["Push to Registry"]
+    Push --> Deploy["Deploy to Cloud Run"]
+    Deploy --> Health{"Health Check"}
+    Health -->|Pass| Live["Live Traffic"]
+    Health -->|Fail| Rollback[Rollback]
+```