Org Chart Builder

---
name: org-chart-builder
description: Use when generating an org chart with hierarchical reporting lines. Triggers on "org chart", "reporting structure", "team structure diagram", "reorg diagram".
---

# Org Chart Builder

Generate a Mermaid `graph TD` org chart with rounded boxes per role, solid lines for direct reports, and dotted lines for matrix relationships. Org charts fail when they conflate org structure with influence, or when they show 100 boxes that no one can read. Show the part that matters.

## Required inputs

1. **Scope** — whole org? one team? one VP's tree? Pick one.
2. **Roles or names** — both is best ("Jamie Chen, VP Product"); roles alone is fine for proposed/draft structures
3. **Direct reporting lines** — who reports to whom (solid line)
4. **Dotted-line / matrix relationships** — who has indirect reporting (designer → product VP solid, → individual PMs dotted)
5. **Open roles** — mark them visually (e.g., "TBH: Senior Engineer") so the audience knows what's hiring vs filled

If the user asks for "the org chart" of a 500-person company, push back: "An org chart with 500 boxes isn't readable. Which sub-tree (or which 3 layers) should we show?"

## Mermaid syntax to use

`graph TD` with rounded boxes `(...)` for people. Solid arrows `-->` for direct reports; dotted arrows `-.->` for matrix / dotted-line reporting. Use `subgraph` only for grouping by function when it adds clarity.

\`\`\`mermaid
graph TD
    VP(VP Product<br/>Jamie Chen)
    PM1(PM, Growth<br/>Alex Lee)
    PM2(PM, Platform<br/>Sam Patel)
    PM3(PM, Mobile<br/>Open role)
    D(Lead Designer<br/>Robin Park)
    E1(PMM<br/>Casey Wu)
    E2(Researcher<br/>Jordan Kim)

    VP --> PM1
    VP --> PM2
    VP --> PM3
    VP --> D
    VP --> E1
    VP --> E2

    D -.-> PM1
    D -.-> PM2
    D -.-> PM3

    classDef open fill:#f9f9f9,stroke:#999,stroke-dasharray: 4 4
    class PM3 open
\`\`\`

Use `<br/>` inside a node label to put role on top and name below — keeps boxes compact.

## Layout principles

- **Top-down (`TD`).** Org charts are vertical. Don't fight it.
- **Role above name** in each box. Role is what matters for understanding the structure; name humanizes it.
- **Solid lines = direct report.** One per person. If someone has two solid-line managers, you have a problem in the org, not the diagram — flag it.
- **Dotted lines = matrix / dotted-line.** Use sparingly; too many dotted lines and the chart becomes spaghetti.
- **Open roles get a distinct style** — dashed border or gray fill. The diagram is less useful if "Open" boxes look like filled ones.
- **Group by function only when it clarifies** — usually the tree itself is the grouping.

## Anti-patterns

- **Whole-company org charts** — past ~30 people they're unreadable. Show the sub-tree relevant to the conversation; link to the full org elsewhere.
- **Mixing IC titles and management titles at the same level** — confuses what reports to what. Use levels consistently.
- **Photos, contact info, fancy styling** — that belongs in an HRIS, not a Mermaid chart. Keep it logical.
- **Showing influence instead of structure** — "this person actually runs the team" is gossip, not org structure. Different diagram.
- **Unmarked open roles** — readers assume every box is a person; "TBH" / "Open" / dashed border is mandatory for unfilled.
- **Solid line to every dotted-line relationship** — turns every person into a hub. Cap dotted lines at the ones that genuinely matter.

## When the chart should be two charts

If the org has both a functional reporting line AND a project / squad structure, you probably want two diagrams: the formal org chart, and a separate "squad map." Trying to show both in one chart with dotted lines everywhere makes both unreadable.

## Rendering hints

- GitHub, Notion, Confluence (with plugin) render Mermaid org charts natively.
- Mermaid Live Editor for SVG export when embedding in a board deck or onboarding PDF.
- For very wide charts (one VP with 12 directs), Mermaid will run them off-screen on narrow pages — consider grouping into subgraphs by function or splitting into sub-trees.

## Output

The ```mermaid block plus a 2-line summary: total boxes, count of open roles, and any "this person reports to two managers" or other structural oddities you noticed while drafting. Org charts are the artifact; the oddities are the value.