Decision Tree Builder

---
name: decision-tree-builder
description: Use when generating a decision tree for triage, troubleshooting, classification, or eligibility logic. Triggers on "decision tree", "triage tree", "if-then diagram", "decision flow with terminal recommendations".
---

# Decision Tree Builder

Generate a decision tree where every path ends in an explicit recommendation. Decision trees fail when leaves are vague ("escalate") or when the tree has unreachable branches. Be exhaustive about leaves; ruthless about depth.

## Required inputs

1. **The decision being made** — what does a leaf node tell you to do?
2. **The questions / criteria** in priority order — what's the FIRST thing you check, then the second?
3. **The terminal outcomes** — list every possible recommendation up front. If you can't enumerate them, you're not ready to draw the tree.
4. **Default / fallback** — what if none of the branches match? Every tree needs a catch-all.

If the user describes a decision with 6+ levels of depth, push back: "Trees over 5 levels deep are unusable in practice. Can we collapse some into a lookup table or split by category first?"

## Mermaid syntax to use

`graph TD` with diamond decision nodes `{...}` and stadium terminal nodes `([...])`. Label every edge with the answer. Use `classDef` to color terminals by severity.

\`\`\`mermaid
graph TD
    Start([Incident reported]) --> Q1{Customer-facing?}
    Q1 -->|Yes| Q2{Revenue-impacting?}
    Q1 -->|No| Q3{Security-related?}
    Q2 -->|Yes| SEV1([SEV1: Page on-call lead])
    Q2 -->|No| SEV2([SEV2: Page on-call])
    Q3 -->|Yes| SEC([Security incident: page security on-call])
    Q3 -->|No| Q4{Affects internal tooling?}
    Q4 -->|Yes| SEV3([SEV3: Ticket, next business day])
    Q4 -->|No| SEV4([SEV4: Backlog])

    classDef high fill:#fdd,stroke:#c00,stroke-width:2px
    classDef low fill:#dfd,stroke:#383
    class SEV1,SEC high
    class SEV3,SEV4 low
\`\`\`

## Layout principles

- **Top-down (`TD`).** Decision trees read top-to-bottom, like a flowchart's older, more disciplined sibling.
- **One question per diamond.** "Is it customer-facing AND revenue-impacting?" should be two diamonds, not one.
- **Order questions by signal-to-effort.** The cheapest, most-informative question goes first.
- **Every path ends in a stadium node `([...])`** with a concrete recommendation — not "escalate" but "Page on-call lead via PagerDuty 'platform-sev1' service."
- **Color terminals by severity / outcome class.** A SEV1 looks different from a SEV4 at a glance.
- **Prefer binary branches** when possible. N-ary branches (3+ children from one diamond) are harder to read but acceptable for true mutually-exclusive enums.

## Anti-patterns

- **Vague leaves** — "escalate" is not a recommendation; "page @oncall in #sev1 with template X" is.
- **Trees over 5 levels deep** — humans lose track. Refactor into a lookup table or two-stage decision (category first, then subtree).
- **Unreachable branches** — every path must be reachable. Walk through and verify.
- **Missing default** — what happens when none of the criteria match? Always include a fallback leaf.
- **Overlapping criteria** — if two branches can BOTH be true, you have a flowchart, not a tree.
- **Soft questions** — "Is it serious?" is opinion. "Is the error rate >1%?" is testable.

## When to NOT draw a tree

If the decision is really a 2D matrix (e.g., severity × customer tier → SLA), a table beats a tree. If outcomes have probabilities, you want a model, not a diagram. If the decision changes weekly, encode it in code, not in a diagram. The tree is an artifact for stable, auditable decisions.

## Rendering hints

- GitHub, Notion, Confluence render Mermaid trees natively.
- For runbooks that get printed (NOC walls, on-call binders), export to SVG via Mermaid Live Editor at high resolution.
- Pair the tree with a 1-line "if you only do one thing" guidance at the top — most readers pattern-match before they trace.

## Output

The ```mermaid block plus a leaf inventory: list every terminal node and the recommendation it produces. If a leaf says "escalate," push back to the user before finalizing. Vague leaves break runbooks.