Root Cause Analysis Gets a Diagram: Introducing Fishbone in Mermaid.js
• 3 mins
Root cause analysis is one of those practices that everyone agrees is important and almost no one enjoys doing. The process of tracing a problem back through its contributing causes gets messy fast — sticky notes on a whiteboard, nested bullet points in a doc, or a spreadsheet that only the original author understands.
Ishikawa diagrams — also called fishbone or cause-and-effect diagrams — were designed specifically to make this structure visible. Since the 1960s, they’ve been a core tool in quality management, Six Sigma, and reliability engineering. And as of Mermaid.js v11.13.0, you can create them directly in your diagrams, docs, and wikis.
What is an Ishikawa diagram?
The diagram resembles a fish skeleton. The “head” is the problem or effect you’re investigating. The “spine” runs horizontally from left to right. “Bones” branch off the spine — each representing a category of causes — and smaller branches represent specific contributing factors within each category.
The classic version uses six standard cause categories, sometimes called the “6 Ms”: Machine, Method, Material, Man (people), Measurement, and Mother Nature (environment). But the categories are flexible — in software contexts, you might use Process, People, Technology, and Tools instead.
The value of the diagram isn’t just the visual structure — it’s the discipline of systematically exploring every dimension of a problem before jumping to conclusions.
The syntax
Mermaid’s Ishikawa syntax is built around indentation. The first line is the problem. Everything that follows is a cause, with depth determined by how far it’s indented.
ishikawa-beta
Slow API Response
Infrastructure
Underpowered instances
No CDN
Code
N+1 queries
Unoptimized indexes
Missing caching
Process
No performance budgets
Reviews skip load testing
The top-level items (Infrastructure, Code, Process) become the major bones. Their indented children become the sub-causes. You can nest as many levels deep as you need.
Where this fits in your workflow
Ishikawa diagrams are most useful at the beginning of a diagnosis, before you’ve decided what the root cause is. They’re a way of making sure you’re not anchoring too quickly on the first plausible explanation.
Some places where Mermaid.js’ fishbone diagram fits naturally:
- Postmortems and incident retrospectives: embed directly in your incident doc
- Architecture decision records: map the contributing factors to a known failure mode
- Sprint retrospectives: “why did this sprint go off track?”
- Product quality reviews: trace customer-reported issues back to their sources
Because it’s text-based, you can version it, diff it, review it in a PR, and collaborate on it the same way you do with code.
A note on beta
The ishikawa-beta keyword is intentional — this is a new diagram type and the syntax may evolve based on community feedback. The core structure (first line = effect, indented lines = causes) is stable, but options for styling, layout, and configuration are still being developed. Full documentation will be published shortly.