# Explanation format

Use when the reader asks why a system, policy, or design is shaped the way it is.

## Great instance

- Names the tension or surprise up front.
- Builds a causal model before giving implications.
- Uses one Mermaid diagram for relationships, flow, or feedback loops.
- Separates facts, interpretation, and consequences.

## Cut

- Step-by-step instructions.
- API tables unless they prove the concept.
- Decorative diagrams that do not change understanding.

## Skeleton

````markdown
# Why <subject> works this way

## The tension
<what seems confusing or costly>

## The model
```mermaid
flowchart LR
  A[Cause] --> B[Mechanism] --> C[Outcome]
```

## What follows
<implications, tradeoffs, and constraints>

## What this does not mean
<misreadings to avoid>
````

## Section prompts

- Make the first paragraph answer the user's actual why.
- Keep the diagram small enough to review as one region.
- Use concrete examples only to clarify the model.
- End by cutting off the most likely wrong conclusion.

## Renderer moves

Catalog: ../building-artifacts.md#what-each-file-type-becomes - md doc reader sections; mermaid region anchors.