Show Me

Help the reader see the current topic. Skip the preamble. Pick the smallest view that makes the point, put it next to the short text it supports, and stop. One view is normal. Several is fine. All of them is too many.

When to use

• The point is shape: control flow, a component tree, file responsibility, a state change.
• Prose would take longer to parse than a sketch.

When to skip

• A sentence already settles it.
• The user asked for a decision or a code change, and a diagram would only decorate it.

Which view

• Pseudocode for logic or an algorithm. Steps, guards, early returns.
• Call tree for runtime control flow. Indent callees. Use a diff fence when the point is what was added or removed. For a real code change, generate that tree with calldiff instead of inventing it.
• Component tree for UI structure. Include the state and module boundaries that matter, and the file that owns each piece.
• File tree for responsibility or a broad refactor. Shallow. Annotate what each directory owns.
• Mermaid for interaction between parts: sequence, data flow, a short state machine.
• Whole block when most of it is new, when omitted context would hide ownership or order, or when the reader needs something they can copy.
• One HTML file when the point is visual layout, a state comparison, or too dense for Mermaid. Match the product's colors, type, and spacing. Use real labels. Then open it.

Keep only the calls, files, props, states, and boundaries needed for the current question.

Output should feel like

• One diagram the reader can check in a few seconds.
• Prose that says what the picture is for, not a tour of every box.

Related

• calldiff — real who-calls-whom trees when the picture is a code change.
• skills-index — vault catalog.