Diagrama de espinha de peixe

Sobre diagramas de espinha de peixe

Um diagrama de espinha de peixe (também chamado de diagrama de Ishikawa ou diagrama de causa e efeito) mapeia as possíveis causas de um problema em uma espinha horizontal que termina no "efeito" — o enunciado do problema. Cada ramo principal representa uma categoria de causas; sub-ramos carregam detalhes contribuintes. Kaoru Ishikawa introduziu a técnica em 1968 como ferramenta de controle de qualidade para manufatura; desde então se expandiu para saúde, engenharia de software e operações de negócio como método estruturado de brainstorming para análise de causa raiz. Equipes o usam em retrospectivas, fases DMAIC Improve, e post-mortems de incidentes para evitar fixação prematura na hipótese mais barulhenta.

O Schematex segue as convenções de causa e efeito do Ishikawa (1968) com as 6M categorias padrão de manufatura (Man, Machine, Material, Method, Measurement, Mother Nature/Environment) e suas variantes de serviço (People, Process, Place, Policy, Procedures, Patron). Dois estilos de autoria — estruturado e compacto — podem ser misturados em um único documento. Referências externas: Ishikawa, K. — Guide to Quality Control (1968) · ASQ Cause-and-Effect Diagram · ISO 9001:2015 §10.2 — Corrective Action.

1. Seu primeiro diagrama de espinha de peixe

O menor diagrama de espinha de peixe útil: três categorias, uma causa cada, uma com sub-causa.

Quatro regras cobrem 80% do uso:

1. Comece com fishbone, opcionalmente seguido de um título entre aspas.
2. Declare cada ramo com category id "Label" — o id é uma chave interna curta, "Label" é o que aparece no diagrama.
3. Adicione causas com id : "texto da causa" em linhas separadas.
4. Indente uma linha com pelo menos 2 espaços e comece com - para criar uma sub-causa (ramo de segunda ordem) sob a causa anterior.

Comentários podem começar com #, //, ou %% no estilo Mermaid em linha própria.

2. Blocos de construção

A espinha e o efeito

effect "Enunciado do problema" coloca o texto na cabeça do peixe. Se effect for omitido, o parser usa o título do diagrama como fallback.

fishbone "Título"
effect "Enunciado específico do problema"

A cabeça fica à direita por padrão (config direction = right). Use config direction = left para invertê-la.

Categorias (ossos principais)

category id "Label" declara um ramo. O id é usado internamente para atribuir causas; o "Label" entre aspas aparece no diagrama.

Categorias também aceitam propriedades opcionais em […]:

category rework "Retrabalho" [color: "#E53935", side: top, order: 1]

Causas (ossos menores)

Dois estilos são aceitos e podem ser misturados em um diagrama:

Estilo A — estruturado. Declare as categorias primeiro, depois atribua causas com id : "texto":

category code "Code"
category infra "Infra"
code : "Consulta N+1 no endpoint"
code : "Camada de cache faltando"
infra : "Atraso no auto-scaling"

Estilo B — compacto. Rótulo de categoria e causas em uma linha, separados por ; ou ,:

category Code: Consulta N+1; Cache faltando; Chamada síncrona
category Infra: Atraso no auto-scaling; CDN mal configurado

No estilo compacto, o id é derivado automaticamente do texto do rótulo (em minúsculas, espaços → hífens). As aspas são opcionais para o texto das causas.

Estilo C — atalho mindmap do Mermaid. Uma linha simples no nível superior se torna uma categoria, e itens - indentados se tornam causas de Nível 1 irmãs sob essa categoria:

fishbone "Por que o site está lento?"
effect "LCP da página > 4s"
Conteúdo
  - imagem hero pesada
  - muito texto acima da dobra
Tech
  - bundle JS muito grande
  - CSS bloqueando renderização

3. Sub-causas (ramos de segunda ordem)

Indente uma linha - com pelo menos 2 espaços após uma causa de Nível 1 para anexar uma sub-causa a ela. O traço - faz parte da sintaxe; o texto o segue.

method : "Abertura do stencil subdimensionada"
  - "Especificação de tolerância da revisão de board de 2018"
  - "Sem revalidação após mudança de material"
method : "Velocidade do pick-and-place muito alta"
  - "Limite de velocidade removido durante hora extra"

Sub-causas aparecem como galhos mais curtos e estreitos ramificando da costela pai.

4. Opções de configuração

Linhas config key = value podem aparecer em qualquer lugar após o cabeçalho. Chaves e valores desconhecidos são silenciosamente ignorados.

config direction = left
config density = compact
config slope = gentle
config sides = top

5. Rótulos e comentários

• Título do diagrama: fishbone "Queda de Tráfego no Site" — primeira linha, opcional.
• Rótulo do efeito: effect "30% de declínio no tráfego orgânico" — o problema na cabeça do peixe.
• Rótulo de categoria: category id "Nome legível" — impresso no ramo.
• Texto da causa: entre aspas "assim" ou sem aspas (espaços permitidos no estilo compacto).
• Texto da sub-causa: após o - inicial, com ou sem aspas.
• Comentários: #, //, ou %% no início de uma linha (após espaço em branco inicial opcional). Os mesmos marcadores também iniciam comentários finais fora de strings com aspas duplas.

6. Palavras reservadas e escape

Reservadas no início da linha: fishbone (cabeçalho), effect, category, config.

O prefixo - em uma linha indentada é reservado como marcador de sub-causa. Para incluir um hífen literal no início do texto de uma causa, use aspas: code : "- caminho antigo depreciado".

Strings com espaços no texto de causa no estilo estruturado devem ter aspas duplas: code : "Consulta N+1". No estilo compacto (category Label: ...) o texto vai até o separador ; ou , e as aspas são opcionais.

Marcadores de comentário (#, //, %%) iniciam um comentário a menos que estejam dentro de uma string com aspas duplas.

7. Erros comuns

8. Gramática (EBNF)

document       = header (blank | comment | effect | category | config | cause | sub-cause | implicit-category)*

header         = "fishbone" ":"? ( WS quoted-string )? NEWLINE
effect         = "effect" ":"? WS quoted-string NEWLINE
config         = "config" WS config-key WS "=" WS config-value NEWLINE
config-key     = "direction" | "width" | "height" | "sides"
               | "slope" | "ribslope" | "density" | "causeside" | "cause-side"
config-value   = bare-word | number | quoted-string

category       = "category" WS id WS label-or-compact ( "[" category-attrs "]" )? NEWLINE
implicit-category
               = bare-text NEWLINE                         # top-level, no ":"

label-or-compact
               = quoted-string                            # structured form: category id "Label"
               | id WS ":" WS compact-causes             # compact form: category Label: cause; cause

category-attrs = category-attr ("," category-attr)*
category-attr  = "color:" quoted-string
               | "side:" ( "top" | "bottom" )
               | "order:" integer

cause          = id WS ":" WS cause-text NEWLINE         # structured form
cause-text     = quoted-string | bare-text

sub-cause      = INDENT≥2 "-" WS cause-text NEWLINE

compact-causes = compact-cause ( (";" | ",") compact-cause )*
compact-cause  = quoted-string | bare-text

comment        = ( "#" | "//" | "%%" ) any NEWLINE
id             = [a-zA-Z] [a-zA-Z0-9_-]*
quoted-string  = '"' any-char-but-unescaped-quote* '"'

Fonte autoritativa: src/diagrams/fishbone/parser.ts. Se isso divergir do parser, o parser prevalece — por favor, abra uma issue.

9. Conformidade com o padrão

Os diagramas de espinha de peixe do Schematex seguem as convenções de causa e efeito do Ishikawa (1968): uma espinha horizontal com uma cabeça rotulada (o efeito) e costelas diagonais para categorias causais principais, cada uma carregando ossos menores (causas individuais). A hierarquia de dois níveis (categoria → causa → sub-causa) corresponde à profundidade de análise tradicional "5 Porquês" usada no DMAIC do Six Sigma e nos fluxos de trabalho de ação corretiva da ISO 9001.

O que está implementado hoje:

• ✅ Estilo estruturado: category id "Label" + id : "causa"
• ✅ Estilo compacto: category Label: causa; causa; causa
• ✅ Sub-causas (Nível 2) via prefixo - indentado
• ✅ Cor e lado por categoria
• ✅ Config de direction, density, slope, sides, causeside
• ✅ width / height explícitos opcionais
• ⏳ Sub-sub-causas de Nível 3+ (o parser armazena filhos, mas o renderizador limita na profundidade 2)
• ⏳ Sugestão automática de conjuntos de categorias padrão (6M, 8P, 5P)
• ⏳ Renderização de order por categoria (parseado, mas ainda não aplicado pelo motor de layout)

Referências:

• Ishikawa, K. (1968). Guide to Quality Control. JUSE Press.
• ASQ — Cause-and-Effect (Fishbone) Diagram
• ISO 9001:2015 §10.2 — Não conformidade e ação corretiva

10. Exemplos relacionados

11. Roadmap

Planejado — ainda não parseável. Não use estes na DSL gerada hoje; o parser irá rejeitar ou ignorar.

• Sub-sub-causas de Nível 3 — um terceiro nível de recuo; a estrutura AST suporta isso, mas o renderizador atualmente para no Nível 2.
• Substituição causeside por categoria — definir cause-side em categorias individuais em vez de globalmente.
• Sugestão automática de categorias padrão — atalho template: 6M / template: 8P que pré-popula os nomes padrão de categorias de manufatura ou serviço.
• Bloco legend — palavra-chave legend para declarar uma chave de codificação de cores renderizada ao lado do diagrama.
• Bloco metadata: — metadados de chave-valor estruturados (facilitador, data, revisão) exibidos em uma anotação de canto.

Acompanhe nas issues do GitHub se você precisar de algum desses em breve.