Diagrams are load-bearing, not decoration. Reach for one only when prose forces the reader to hold a whole shape in their head at once — then pick the smallest view that lets them see the shape instead of reconstructing it from sentences. Everything here renders in the conversation as text blocks or Mermaid; at most one artifact file is ever written.

The vocabulary

Pick one view; two at most. More is noise.

Pseudocode — logic without language noise. Reduces a decision to its branching shape:

on(request)
  if state file locked by another writer
    queue and return pending
  acquire lock
  write
  release

Call tree — runtime control flow. Depth shows who owns the flow; annotate where the interesting edge is:

diagram

The vocabulary