Diagrama

Los diagramas soportan carga, no son decoración. Recurre a uno solo cuando la prosa obliga al lector a mantener una forma completa en la cabeza de una vez — entonces elige la vista más pequeña que le permita ver la forma en lugar de reconstruirla a partir de oraciones. Todo lo que hay aquí se renderiza en la conversación como bloques de texto o Mermaid; como máximo se escribe un archivo de artefacto.

El vocabulario

Elige una vista; como máximo dos. Más es ruido.

Pseudocódigo — lógica sin ruido de lenguaje. Reduce una decisión a su forma ramificada:

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

Árbol de llamadas — flujo de control en tiempo de ejecución. La profundidad muestra quién controla el flujo; anota dónde está el borde interesante:

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

Árbol de componentes — estructura de UI o módulos, con los límites que importan anotados en línea:

<SettingsPage> (src/routes/settings)
  <SessionList> (maneja sus propias peticiones)
  <DangerZone>
    <ConfirmButton> (deshabilitado hasta confirmación escrita)

Árbol de archivos — dónde reside la responsabilidad; mantenlo poco profundo, una anotación por directorio:

src/
├── hooks/        # registro de hooks + tipos
├── tools/        # manejadores de herramientas MCP
└── workflow/     # registro + proyecciones

Mermaid — interacción entre partes, flujo de datos o transiciones de estado:

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

Diff — la forma de un cambio cuando la estructura circundante ya existe. Haz coincidir el diff con el tema:

un cambio de componente:

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

un cambio de diseño de archivos:

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

un cambio de flujo de control:

 commit()
   stage()
     hashBlobs()
+  writeObject()
   updateRef()
+    acquireStateFileLock()

un cambio de máquina de estados:

 on(request)
-  write immediately
+  if locked
+    queue and return pending
+  acquire lock
+  write
+  release

El bloque completo — cuando omitir partes ocultaría quién posee qué o el orden en que se ejecutan las cosas, muestra la unidad completa una vez, que se pueda copiar:

export function isRegistryEnabled(): boolean {
  const flag = process.env.OMC_WORKFLOW_REGISTRY;
  return flag !== '0' && flag !== 'false';
}

Cuando el texto se agota

Un diseño de UI, una comparación antes/después, o un concepto demasiado denso para Mermaid: escribe un archivo HTML enfocado — un diagrama, una infografía o unas pocas diapositivas — estilizado con los colores, tipos y componentes propios del producto, lleno de etiquetas y datos reales, que funcione en escritorio y móvil. Ábrelo con el abridor de la plataforma (start en Windows, open en macOS, xdg-open en Linux) y detente ahí: un artefacto, no una galería.

Disciplina

• Coloca cada visual directamente junto a las dos o tres frases que apoya.
• Lleva solo las llamadas, archivos, props, estados y límites que respondan a la pregunta actual — cada nodo extra es un impuesto de decodificación para el lector.
• Si la respuesta honesta cabe en una oración, escribe la oración.