598db63a70
Implement a mandatory State Machine model (PLAN and IMPLEMENTATION states) in root instructions to prevent the AI from generating code prematurely. The rules require mechanical reloading of skill files during execution to combat context-window memory loss. Also update Mermaid diagram instructions to explicitly ban <br> tags for newlines and prohibit raw angle brackets (<, >) in nodes, enforcing real newlines and HTML entities (<, >) to fix rendering issues.
96 lines
2.3 KiB
Markdown
96 lines
2.3 KiB
Markdown
# Mermaid Diagram Instructions
|
|
|
|
---
|
|
|
|
## Edge Labels
|
|
|
|
Use `-- "text" -->` syntax, **not** `-->|text|` syntax.
|
|
|
|
`|` inside `-->|label|` breaks parsing if the label contains a pipe character (e.g. `curl | bash`). Quoted syntax always works:
|
|
|
|
```
|
|
✅ A -- "curl | bash" --> B
|
|
❌ A -->|curl | bash| B
|
|
```
|
|
|
|
---
|
|
|
|
## Line Breaks (Multiline Text)
|
|
|
|
Do not use `\n`, `<br>`, or `<br/>` for line breaks inside Mermaid nodes or labels. They do not always render correctly.
|
|
Instead, use actual line breaks (real newlines) inside quoted text.
|
|
|
|
```
|
|
✅ A["First line
|
|
Second line"]
|
|
|
|
❌ B["First line\nSecond line"]
|
|
❌ C["First line<br/>Second line"]
|
|
```
|
|
|
|
---
|
|
|
|
## Angle Brackets and Special Characters
|
|
|
|
Do not use raw `<` or `>` characters in Mermaid nodes or labels (e.g. `<customer>-idp-deployment`), as they are often parsed as HTML tags and break rendering.
|
|
Instead, use HTML entities `<` and `>`.
|
|
|
|
```
|
|
✅ A["<customer>-idp-deployment"]
|
|
|
|
❌ B["<customer>-idp-deployment"]
|
|
```
|
|
|
|
---
|
|
|
|
## Color Contrast — CRITICAL
|
|
|
|
All Mermaid diagrams MUST have sufficient color contrast. AI-generated diagrams often fail this.
|
|
|
|
**Rule**: always pair background with explicit text color.
|
|
|
|
| Background type | Text color |
|
|
|----------------|------------|
|
|
| Light (`#e6ffe6`, `#ffcccc`, `#fff3cd`) | `color:#000` |
|
|
| Dark (`#009900`, `#cc0000`, `#0055cc`) | `color:#fff` |
|
|
| Default (no fill) | no color needed |
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[Input]:::good --> B[Process]:::bad --> C[Output]:::good
|
|
classDef good fill:#009900,color:#fff
|
|
classDef bad fill:#cc0000,color:#fff
|
|
```
|
|
|
|
**Never**:
|
|
```
|
|
style NodeA fill:#ffcccc ❌ no text color — unreadable
|
|
style NodeB fill:#66ff66 ❌ bright color, no contrast defined
|
|
```
|
|
|
|
---
|
|
|
|
## Size
|
|
|
|
- **Abstract diagram**: max 5-7 nodes — full scope, high level
|
|
- **Section diagrams**: max 3-5 nodes — one subsystem only
|
|
- Too many arrows = diagram is wrong scope, split it
|
|
|
|
---
|
|
|
|
## When to Use What
|
|
|
|
| Situation | Use |
|
|
|-----------|-----|
|
|
| Flows, sequences, architecture | Mermaid `graph` or `sequenceDiagram` |
|
|
| File/folder structure | ASCII tree |
|
|
| Timeline | Mermaid `gantt` |
|
|
| Both structure and flow needed | Both, separately |
|
|
|
|
---
|
|
|
|
## If Diagram Would Be Too Complex
|
|
|
|
Do not simplify by removing important nodes.
|
|
Instead: split into two diagrams — one high-level, one zoomed-in detail.
|