Fishbone diagrams

TL;DR

Ask your agent

Use Plotwork to draw a fishbone diagram of why checkout errors rose after our last release. Group the causes under People, Process, Infrastructure and Code, and mark the small connection pool as the confirmed root cause.

Use Plotwork to draw a fishbone diagram of the causes in this incident review. Use the 6M categories, put sub-causes under the cause they explain, and give each category an icon.

Example

An incident review: four categories, a sub-cause under the review that missed the change, and the confirmed root cause in red.

PictureSourceOutline

A manufacturing defect with the 6M categories

The six categories of the 6M set, in their usual order. The confirmed cause holds the two sub-causes the team traced it to.

PictureSourceOutline

A slow build, with the head on the left

side=left puts the head at the left, for a page that reads from the problem outward. Two causes are marked, in two tones.

PictureSourceOutline

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment. A block opens with { at the end of a line and closes with } on a line of its own.

The header

fishbone "Title" side=right desc="<text>". The title and both options are optional. side= is right, the default, or left, and puts the head at that end of the spine. desc= is the plain-language description for assistive technology.

Statements

The effect

The effect is the problem the causes lead to. Write it once, above the categories. It is drawn on a solid card at the end of the spine, the strongest thing in the picture. Without an effect line the title stands in, and without either the head reads Effect.

Categories

Each category is a bone. Categories alternate above and below the spine in the order written, from the tail toward the head, and are never reordered, because the order often carries meaning. A category's card holds its label and an optional icon; tone= colours the bone and the card.

Two common sets of categories are a good start:

A software team often uses People, Process, Infrastructure, Code, and Dependencies. A category with no causes draws a bare bone, and lint warns about it.

Causes and sub-causes

A cause is a tick off its bone with its text beside it. A cause that ends with { holds sub-causes, drawn on shorter ticks from a stem under the cause, in a quieter type. A sub-cause holds nothing: a fourth level is refused with E140, and the hint suggests folding the detail into the sub-cause text.

Each bone is as long as its side's longest list of causes, so the cards stay in a row. Bones are spaced along the spine by the room their text needs, so causes never touch another bone or each other.

Confirmed causes

tone= on a cause or a sub-cause marks it as confirmed. Its text and tick are drawn in that tone, a dot marks where it meets the bone, and a key under the picture says "Confirmed cause". The text description lists every confirmed cause with its category. Use tone=red for the root cause and, if you need a second mark, tone=amber for a likely one.

Limits and warnings

Every mistake comes back as a result with a code, a line, a column, and a hint. Warnings never stop the drawing.

From Mermaid

Mermaid's Ishikawa diagram (ishikawa-beta, and ishikawa) converts to a fishbone diagram. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full. Mermaid gives the structure by indentation: the first line is the problem, the lines after it at the next level are categories, and deeper lines are causes.

1ishikawa-beta2    Blurry Photo3    Process4        Out of focus5        Shutter speed too slow6    User7        Shaky hands8    Equipment9        LENS10            Inappropriate lens11            Dirty lens12    Environment

It becomes:

1fishbone "Blurry Photo"2effect "Blurry Photo"3
4category process "Process" {5  cause "Out of focus"6  cause "Shutter speed too slow"7}8
9category user "User" {10  cause "Shaky hands"11}12
13category equipment "Equipment" {14  cause "LENS" {15    cause "Inappropriate lens"16    cause "Dirty lens"17  }18}19
20category environment "Environment"

Mermaid has no way to mark a confirmed cause, so after converting, add tone=red to the root cause, an icon= to each category, and ids that say what each category is.

See also