---
name: mermaid-fixer
description: Fix Mermaid diagram syntax errors in Markdown files. Use when: (1) Mermaid diagrams aren't rendering or show parse errors, (2) User mentions "mermaid syntax error", "mermaid not working", "diagram broken", (3) CI/CD fails on Mermaid validation, (4) Documentation contains Mermaid code blocks that need fixing.
---

# Mermaid Diagram Fixer

Automatically detects and fixes Mermaid diagram syntax errors in Markdown files using the `check-mermaid.js` validation script.

## How It Works

1. **Run `check-mermaid.js`** to get detailed error reports
2. **Parse error information** (line numbers, error types, code snippets)
3. **Apply intelligent fixes** based on the specific error
4. **Verify** by running the check again

## Core Script

The `scripts/check-mermaid.js` script is the heart of this skill. It:
- Scans Markdown files for ```` ```mermaid ```` code blocks
- Validates each block using the Mermaid CLI (`mmdc`)
- Returns detailed error reports with line numbers and error messages

## Workflow

### Step 1: Run the Check Script

```bash
node scripts/check-mermaid.js <path/to/file.md>
```

**Expected output format:**

- **No errors**: Returns exit code 0 with success message
- **Has errors**: Returns exit code 1 with structured error report:

```markdown
## 🚨 Mermaid 语法检查报告

**检查文件：** `example.md`
**检查结果：** ❌ 发现 2 处语法错误 (共检测到 5 个代码块)

---

### ❌ 错误 #1 (代码块 #2)

- **文档位置：** 第 `51` 行至第 `86` 行

#### 核心错误详情
\`\`\`text
Error: Parse error on line 13: ...
Expecting 'SQE', 'DOUBLECIRCLEEND', ... got 'PS'
\`\`\`

#### 代码内容片段
\`\`\`text
[shows the problematic code]
\`\`\`
```

### Step 2: Parse and Understand Errors

Key information from each error:
- **文档位置**: Which line numbers contain the error
- **核心错误详情**: The parser error message
- **代码内容片段**: The actual Mermaid code causing the issue

### Step 3: Apply Fixes Based on Error Type

#### Error Type: "got 'PS'" (Parentheses Issue)

**Cause**: Parentheses `()` in node labels or arrow labels within subgraphs

**Fix**: Quote the label
```mermaid
# Before (causes error)
NodeA[Label (with parens)]
-->|Label (parens)| NodeB

# After (fixed)
NodeA["Label (with parens)"]
-->"|Label (parens)|" NodeB
```

#### Error Type: "got 'SQS'" (Square Brackets Issue)

**Cause**: Square brackets `[]` in node labels

**Fix**: Quote the label
```mermaid
# Before
NodeA[Result[]<br/>text]

# After
NodeA["Result[]<br/>text"]
```

#### Error Type: "got 'DIAMOND_START'" or similar

**Cause**: Curly braces `{}` or other special characters in labels

**Fix**: Quote the label
```mermaid
# Before
NodeA[Label {variable}]

# After
NodeA["Label {variable}"]
```

### Step 4: Apply the Fix to the File

1. Read the Markdown file
2. Locate the problematic code block using the reported line numbers
3. Apply the appropriate fix (quote labels with special characters)
4. Save the file

### Step 5: Verify

Run `check-mermaid.js` again to confirm all errors are resolved.

## Common Fix Patterns

| Error Pattern | Fix Strategy |
|---------------|--------------|
| `NodeID[label (text)]` | Change to `NodeID["label (text)"]` |
| `-->|label (text)|` | Change to `-->|"label (text)"\|` |
| `NodeID[label[]text]` | Change to `NodeID["label[]text"]` |
| `NodeID[label{text}]` | Change to `NodeID["label{text}"]` |

## Important Notes

1. **Always quote labels** containing: `()`, `[]`, `{}`, `<`, `>`, `#`, or Chinese characters
2. **Preserve the original structure** - only modify the problematic labels
3. **Check all reported errors** - don't stop after fixing just one
4. **Re-verify** after each fix round

## Example Usage

```
User: "My Mermaid diagrams in docs/architecture.md aren't rendering"

Claude:
1. Run: node scripts/check-mermaid.js docs/architecture.md
2. Parse error output
3. Identify errors (e.g., "got 'PS'" on line 45)
4. Read file, locate line 45, find the Mermaid block
5. Apply fix: quote labels with parentheses
6. Save and verify
```