moilanik 598db63a70 docs(ai): introduce state machine flow and Mermaid rendering rules

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 (&lt;, &gt;) to fix rendering issues.

2026-04-13 10:38:16 +03:00

2.3 KiB

Raw Blame History

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["&lt;customer&gt;-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.

2.3 KiB Raw Blame History