You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Encourage mermaid diagrams instead of discouraging them
The previous prompting was too conservative, causing the agent to
almost never generate diagrams even for architecture/flow pages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: workflows/agentic-wiki-writer.md
+13-12Lines changed: 13 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -468,18 +468,19 @@ Do NOT start any page with an H1 heading (`# Title`). The page title is already
468
468
469
469
GitHub wiki supports rich markdown features. Use them when they genuinely clarify — never for decoration. Plain prose is the default.
470
470
471
-
**Mermaid diagrams** — Most pages should NOT have a diagram. Only include one when the concept has spatial or temporal relationships that prose cannot efficiently convey.
472
-
473
-
Use a diagram when:
474
-
- 3+ components interact and the reader needs to see how data/control flows between them
475
-
- An entity has a non-obvious state lifecycle with multiple transitions
476
-
- The instruction explicitly asks for a diagram or data flow
477
-
478
-
Do NOT use a diagram when:
479
-
- The flow is linear (A then B then C) — a sentence or bullet list is clearer
480
-
- It would merely restate what surrounding bullet points already say
481
-
- The page documents a list of things rather than how things connect
482
-
- It would have fewer than 4 nodes or more than 15 nodes
471
+
**Mermaid diagrams** — Include a diagram on any page where it helps the reader understand relationships, flows, or architecture. Most pages that describe how components interact, how data flows, or how processes work benefit from a diagram.
472
+
473
+
Include a diagram when:
474
+
- The page describes architecture, pipelines, or system components
475
+
- 2+ components interact and a visual clarifies the relationships
476
+
- There is a data flow, request/response exchange, or state lifecycle
477
+
- The instruction mentions workflows, CI/CD, build processes, or integrations
478
+
- The page would otherwise be a wall of text describing interconnected parts
479
+
480
+
Skip a diagram only when:
481
+
- The page is a simple reference list (config options, API parameters)
482
+
- A diagram would have fewer than 3 nodes
483
+
- The content is purely procedural (step 1, step 2, step 3) with no branching
483
484
484
485
Diagram type by use case: `flowchart LR` for architecture/data flow; `sequenceDiagram` for multi-step request/response exchanges; `stateDiagram-v2` for lifecycles; `classDiagram` only when 3+ types have non-obvious relationships.
0 commit comments