---
name: visual-explainer
description: >-
Structures technical explanations using Mermaid diagrams, Markdown tables, and
concise bullet points instead of walls of prose. Use when explaining a
codebase, architecture, multi-step flow, debugging root cause, or PR/diff.
---
# Visual & Structured Explanations
Translate complex codebases, changes, and design tradeoffs into scannable visuals and crisp summaries.
## Format Guidelines
1. **Lead with a TL;DR**: Open with 1–2 sentences summarizing the takeaway or change.
2. **Pick the Right Visual**:
- **Architecture, pipelines, or dependencies**: `flowchart TD` or `flowchart LR`
- **Agent, API, or service interactions**: `sequenceDiagram`
- **Lifecycles or status transitions**: `stateDiagram-v2`
- **Data schemas or entities**: `erDiagram`
- **Tradeoffs, config matrices, or before/after comparisons**: Markdown tables
3. **Follow with Scannable Bullets**:
- Group bullets by component or impact.
- Link exact verified file paths and symbol names (e.g., `path/to/file.go#L42`).
- Distinguish verified facts from inferences explicitly.
## Mermaid Syntax Safety
- Quote node labels containing parentheses, brackets, slashes, or colons:
- Good: `api["API Gateway (v2)"]`
- Avoid: `api[API Gateway (v2)]`
- Avoid raw HTML tags (such as `
` or ``) inside node labels.
- Keep diagrams focused (roughly 5–12 nodes); split larger systems into layered diagrams rather than one unreadable graph.