Diagram

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:

acquireStateFileLockSync()
  resolveLockPath()
  openExclusive()
  writePid()

Component tree, UI or module structure, with the boundaries that matter annotated inline:

<SettingsPage> (src/routes/settings)
  <SessionList> (owns its fetches)
  <DangerZone>
    <ConfirmButton> (disabled until typed confirmation)

File tree, where responsibility lives; keep it shallow, one annotation per directory:

src/
├── hooks/        # hook registry + types
├── tools/        # MCP tool handlers
└── workflow/     # registry + projections

Mermaid, interaction between parties, dataflow, or state transitions:

sequenceDiagram
    participant CLI
    participant Hook
    participant State
    CLI->>Hook: PreToolUse
    Hook->>State: read mode
    Hook-->>CLI: allow / deny + facts

Diff, the shape of a change when the surrounding structure already exists. Match the diff to the topic:

a component change:

 <SettingsPage>
   <SessionList />
   <DangerZone>
+    <ConfirmButton />
   </DangerZone>

a file-layout change:

 src/tools/
-└── state-tools.ts
+└── state-tools/
+   ├── handlers.ts
+   └── schema.ts

a control-flow change: