Cursor rule

1---
2description:
3globs:
4alwaysApply: false
5---
6# Create GitHub-Compatible Mermaid Diagrams
7 
8**Your Task: When asked to create a diagram, generate it using Mermaid syntax suitable for rendering directly in GitHub Flavored Markdown. Store the diagram in a new file at `docs/diagrams/<diagram-name>.md`. Adhere strictly to the following rules to ensure compatibility and readability.**
9 
10## File Existence Check
11 
12Run the following command to see which source documents are available:
13 
14```bash
15ls . docs
16```
17 
18Use the output to know which files exist before proceeding.
19 
20## I. Preliminary Step: Gather Context for the Diagram
21 
22Before generating any diagram, you **MUST** attempt to read and understand the content of the following project documents (if they exist and are relevant to the diagram request):
23 
24- `NOTES.md`
25- `docs/PRD.md` (Product Requirements Document)
26- `docs/TECH_STACK.md`
27- `docs/openapi.yaml` (or other API specifications)
28- Any other architecture or design documents in `docs/` related to the subject of the diagram.
29 
30This context is essential for creating an accurate and meaningful diagram.
31 
32## II. Core Diagramming Rules for GitHub Mermaid
33 
341.  **Correct Fenced Code Block:**
35    - Always start the Mermaid block with triple backticks and `mermaid`: `` ```mermaid ``.
36    - Always end the block with triple backticks: ` ``` `.
37    - **Example:**
38```markdown
39        ```mermaid
40        graph TD
41          A[Start] --> B{Decision};
42          B -- Yes --> C[Action 1];
43          B -- No --> D[Action 2];
44```
45```
46 
472.  **Use Well-Supported Diagram Types:**
48    GitHub generally has good support for these common types:
49    - `graph` (Flowcharts - `TD` or `TB` is often best for readability)
50    - `sequenceDiagram`
51    - `classDiagram`
52    - `stateDiagram-v2` (Prefer v2 for better features/rendering)
53    - `erDiagram` (Entity Relationship)
54    - `pie` (Pie charts)
55    - `gantt` (Gantt charts)
56    - `mindmap` (Basic indented structure only - **NO ICONS**)
57    - *Avoid newer or less common diagram types, as GitHub's Mermaid version may not be the latest.*
58 
593.  **General Syntax Best Practices:**
60    - **Node IDs:** Use simple alphanumeric IDs (e.g., `node1`, `processA`). Avoid spaces or special characters in IDs.
61    - **Node/Actor/State Labels (CRITICAL):** **ALWAYS use double quotes (`"..."`)** for labels, especially if they contain spaces, punctuation, special characters (like hyphens, periods, colons), or Mermaid keywords. This is the most common source of rendering errors.
62        - **Correct:** `A["User Input: Text"] --> B["Validate Data (Step 1)"];`
63        - **Incorrect (Potential Error):** `A[User Input: Text] --> B[Validate Data (Step 1)];`
64    - **Arrows:** Use standard arrow types (`-->`, `---`, `==>`, `->>`, etc.).
65    - **Comments:** Use `%%` for comments within the Mermaid code if needed (e.g., `%% This is a comment %%`).
66 
674.  **`mindmap` Specifics for GitHub:**
68    - GitHub **supports the basic `mindmap` structure** using indentation (spaces or tabs) to define hierarchy.
69    - Each node/item **MUST** be on its own line with correct indentation relative to its parent.
70    - GitHub **DOES NOT support** advanced `mindmap` features like `::icon()` syntax. Using icons **WILL CAUSE RENDERING ERRORS**.
71    - Stick to plain text nodes for mind maps.
72    - **Correct `mindmap` (GitHub Compatible):**
73        ```mermaid
74        mindmap
75          Root
76            Parent Node
77              Child Item 1
78              Child Item 2
79```
80    - **Incorrect `mindmap` (GitHub Incompatible - Uses Icons):**
81```mermaid
82        mindmap
83          Root
84            ::icon(fa fa-star) Parent Node
85              ::icon(fa fa-one) Child Item 1
86```
87 
885.  **Layout Preference for Flowcharts (`graph`):**
89    - For `graph` diagrams, prefer `TD` (Top Down) or `TB` (Top Bottom) for better readability within Markdown document flow. Example: `graph TD;`.
90 
916.  **Styling: Let GitHub Handle It (CRITICAL):**
92    - **DO NOT** attempt to set themes (e.g., `%%{init: {'theme': 'dark'}}%%`).
93    - **DO NOT** try to apply custom styling using `classDef`, `style`, or inline CSS attributes *within the Mermaid code*.
94    - GitHub **ignores** these directives and applies its own styling based on the user's current GitHub theme (light, dark, or dimmed). Your diagram will adapt automatically. Forcing themes or styles will likely be ignored or look inconsistent.
95 
967.  **Keep Diagrams Focused and Manageable:**
97    - Avoid overly complex diagrams with an excessive number of nodes, edges, or deep nesting in a single block. While GitHub can render complex diagrams, they might become hard to read or hit rendering performance limits.
98    - If a concept is very complex, consider breaking it down into multiple, simpler, linked diagrams.
99 
1008.  **Verification (If Possible):**
101    - If you have access to a GitHub Markdown preview environment, use it to test your Mermaid syntax. This is the best way to catch errors.
102 
1039.  **Note on Automated Edits:**
104    - Be aware that automated code editing tools may sometimes struggle with precise changes within Mermaid blocks, especially with syntax sensitive to indentation (like mindmaps) or quoting.
105    - **Always carefully review any automated edits** made to Mermaid blocks. If errors occur or the diagram doesn't render as expected, manual correction might be required.
106 
107## III. Output File
108 
109- Place the generated Mermaid diagram (within its fenced code block) into a new Markdown file.
110- Save the file to `docs/diagrams/<diagram-name>.md`, where `<diagram-name>` is a descriptive name for the diagram (e.g., `user-authentication-flow.md`, `database-schema.md`).
111 
112**REMEMBER: Your goal is to create a clear, accurate Mermaid diagram in `docs/diagrams/<diagram-name>.md` that renders correctly on GitHub. Key success factors are: using ` ```mermaid `, quoting all labels meticulously (`"Like This!"`), avoiding themes/custom styles, and for mindmaps, using only basic indentation (NO icons). Always gather context from project docs first.**
113