visualize

name	visualize
description	Use when content needs a diagram or visual — auto-detects content shape, picks the best format per the active-selection rule, and renders it.

/visualize

Auto-detect content shape and render the appropriate visualization. Follows the active-selection rule from ai-workspace/rules/visualizations.md.

Usage

/visualize                              # visualize the last discussed concept
/visualize <topic or file>              # visualize specific content
/visualize --format mermaid <topic>     # force a specific format

Steps

1. Identify content. From args, recent conversation context, or a file path. Determine what needs visualizing.

2. Classify content shape. Use this decision table:

   Content shape	Signal	Format
   Graph with nodes + edges	architecture, dependencies, flow between components	Mermaid graph or flowchart
   Sequence / interaction	request flow, API calls, multi-step protocol	Mermaid sequenceDiagram
   State transitions	modes, lifecycle, status changes	Mermaid stateDiagram-v2
   Comparison (3+ items)	options, tradeoffs, feature matrix	Markdown table
   Hierarchy / tree	file structure, org chart, simple nesting	ASCII art
   Contrast (2 items)	before/after, good/bad, do/don't	Inline pairs
   Entity relationships	data model, schema	Mermaid erDiagram

3. Check render surface. Mermaid in committed .md files renders on iOS/web/GitHub/VS Code. In terminal chunks, Mermaid is literal text — use ASCII instead. When surface is unknown, default to ASCII.

4. Render.

   • ASCII / table / inline pairs: output directly in the response.
   • Mermaid: output as a fenced mermaid code block in the response. If high-resolution PNG is needed:

     node --import tsx "${SKILL_DIR}/scripts/render-mermaid.ts" --input <mermaid-file> --output <png-path> --width 2400 --height 1800
     

   • Format override: if user passed --format, use that format regardless of auto-detection.

5. Present. Show the visualization. If Mermaid PNG was rendered, display the path.

Failure modes

Condition	Behavior
Content shape ambiguous	Ask: "This could be a [X] or [Y] — which fits better?"
Mermaid syntax error	Show the error, offer to fix
mmdc not available	Fall back to fenced Mermaid block (renders on GitHub/web)

Cross-tool notes

• Codex / Cursor: run scripts/render-mermaid.ts directly for PNG rendering. Content-shape detection is agent reasoning, not script logic.