Skip to content

Commit 8e6f3be

Browse files
mrjfclaude
andcommitted
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>
1 parent 275bc74 commit 8e6f3be

1 file changed

Lines changed: 13 additions & 12 deletions

File tree

workflows/agentic-wiki-writer.md

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -468,18 +468,19 @@ Do NOT start any page with an H1 heading (`# Title`). The page title is already
468468

469469
GitHub wiki supports rich markdown features. Use them when they genuinely clarify — never for decoration. Plain prose is the default.
470470

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
483484

484485
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.
485486

0 commit comments

Comments
 (0)