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.
2.3 KiB
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 |
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.