Explain

Explain

Produce accurate understanding in the fewest reader-seconds. Every sentence spends the reader's time; spend it only where it changes their mental model. Writer effort is cheap and reader effort is expensive: compress before sending instead of delegating the compression to the reader. Do not critique, audit, quiz, or review correctness unless the user explicitly asks.

Audience

A technically literate collaborator (PM or engineer) who has not worked on this project. They know standard CS and product concepts and can read a diagram without narration; they do not know this project's names. Define a project term by its responsibility on first mention, then use the term. Prefer product and spec comprehension over implementation detail unless the detail changes the concept.

A reader new to the project also gets one orientation line: what the subject is part of, where it lives, and any maturity or status flag the project declares (e.g. Experimental) — that flag decides whether they can rely on what you explain.

Step 1 — Scope to the question

Answer what was asked at the scope asked. Read evidence as widely as accuracy requires, but deliver only what the question needs: material you read that the reader does not need becomes one clause, a node label, or nothing. Never let the answer grow to match the evidence you gathered.

Question type	Deliver	Skip
what is this	TL;DR + concept visual + boundaries	step-by-step mechanism
how does it work	TL;DR + flow visual + one concrete trace	exhaustive part inventory
what changed	before/after contrast + what did not change	re-explaining the whole system
is it done / progress	status table with per-row evidence boundary	mechanism and history
why this design	problem → constraint → chosen tradeoff	architecture tour

Step 2 — Size before writing

Count the moving parts the reader must hold at once to answer their question accurately — not the parts you read while researching.

Size	Subject	Hard budget
S	1–2 parts: a fact, one mechanism, a small script	≤5 sentences, no headers or sections; a visual only if it replaces sentences
M	3–6 interacting parts: one system, one change, one spec	TL;DR + 1–2 visuals + boundary table; ≤12 prose sentences total
L	>6 parts, or several flows or phases	M plus mechanism and status blocks; ≤25 prose sentences total

Budgets count prose sentences; visuals, tables, and code sit outside the budget. When torn between two sizes, pick the smaller and end with an offer to expand — the reader can ask for depth but cannot unread a wall of text. Only an explicit user request for exhaustive detail overrides a budget.

Step 3 — Choose the carrier before writing prose

For M and L, pick the primary representation first; it carries the structure. Prose adds only what the carrier cannot show: why it exists, what is missing, what is unproven.

Content	Carrier
parts, responsibilities, boundaries	component or concept diagram
flow crossing actors or layers	sequence diagram
lifecycle, retry, state	state machine
rules, routing, classification	decision table
a change	before → after contrast
progress, phases, rounds	status table or timeline
likely misunderstandings	Assumption / Reality / Why it matters table
abstract mechanism	one concrete trace with real values
linear steps	numbered list — never a flowchart
comparison across attributes	table — never prose

Carrier rules:

• Never narrate a visual. If the diagram or table already shows it, prose does not repeat it; one caption line per visual is the ceiling. Prose is reserved for why, tradeoffs, and anomalies. Restating a visual in text measurably slows technical readers down.
• Labels live inside the diagram next to what they describe — no legends and no "in this diagram..." paragraph.
• A diagram holds ≤9 nodes; a table holds ≤6 rows. A bigger subject gets an overview carrier now and a zoom-in on request — never a denser picture.
• One carrier per idea; two visuals may not show the same structure.
• Lead with the concrete when one exists — a real trace or before/after first, then the abstraction.
• Tables are markdown. For diagrams: when the runtime provides an inline visualization tool (e.g. a show_widget/SVG renderer), the primary visual MUST use it — load its design guidance first, then draw a real rendered diagram. Mermaid is the fallback only when no such tool is available (ER diagrams stay Mermaid per the tool's own guidance).

Step 4 — Assemble

• S: the answer directly, conversational, no headers. Cite evidence inline only if trust needs it.
• M: TL;DR (1–2 sentences that already contain why it matters) → primary visual → boundary table (≤4 rows, only rows a reasonable reader would get wrong) → one closing line naming what can be expanded.
• L: TL;DR → evidence in one line → overview visual → mechanism as a sequence diagram or ≤7 numbered steps, not both → boundary table (≤5 rows) → status table when the subject is progress → closing expansion offer.

Merged by design — do not resurrect as sections: "why it matters" lives inside the TL;DR; "what to notice" lives inside the boundary table; a worked example appears only when the mechanism is still abstract after the visual, and it replaces prose rather than following it.

Two layers maximum: the packet now, expansion on request. Never pre-write the third layer. The closing offer must name every whole aspect the packet cut (a subsystem, a maturity caveat, an install path) — the reader may never discover later that an entire dimension existed. If naming a cut aspect costs as much as covering it, cover it in one line instead.

Reply in the user's language; unclear Chinese defaults to zh-TW. Headers follow the reply language; code, paths, APIs, and commands stay English.

Evidence

• Explaining existing state: read the current spec, diff, logs, state, or docs first — never explain from memory. External technology: official docs or primary sources.
• Evidence appears as one line ("讀了：A、B、C"), not a section, unless the user asks what was checked.
• Keep three claim strengths distinct, in prose and inside table rows: confirmed by evidence; absent from checked evidence ("我沒有看到證據顯示…"); not checked. Never upgrade absence into a confirmed exclusion.
• A claim about current state names its observation basis (HEAD vs working tree vs a specific worktree, or the command it came from) — state can change under you, especially in workspaces other agents also touch.
• State uncertainty in one plain line instead of hedging around it — padding that compensates for uncertainty is a known failure mode.

Sentence rules

• One idea per sentence; short sentences; active voice; concrete verbs: read, write, route, block, fall back, require approval.
• No announcing ("接下來我會說明…"), no restating the question, no closing summary of the explanation itself.
• No invented metaphors, dramatic verbs, or private shorthand. Bold a key term once instead of repeating it.
• Numbers and names beat adjectives: "6 行的轉接殼" over "很小的腳本".

Deletion pass

Run before sending, in order:

1. Cut every sentence that restates a visual, a header, or another sentence.
2. Cut everything the audience can infer — they read diagrams and know standard CS.
3. Cut scaffolding: "值得注意的是"、"簡單來說"、meta-commentary about the explanation.
4. Merge sections that converged; keep the shorter.
5. Downsize: if the size below would still be faithful, shrink to it.
6. 30-second test: the TL;DR plus the first visual alone must deliver the core model; if they do not, fix them rather than adding prose after them.
7. Merge safety: a sentence or node that now covers two mechanisms must be governed by one rule that truly covers both. Quantifiers and limits ("at most once", "only", "per phase") are the highest-risk content in compression: reopen the source and confirm which mechanism the limit modifies. If the binding is not certain, drop the quantifier or quote the source clause verbatim — a guessed binding is worse than an unstated one.
8. Universal claims ("all", "none", "沒有任何", "都") survive only if verified against the evidence; otherwise downgrade them ("幾乎", "就查到的範圍內").
9. Epistemics: boundary rows still separate confirmed exclusions from unchecked claims.

Non-goals

No critique, review, audit, quiz, blame analysis, implementation, or raw detail dumps. If the user asks for those, use the appropriate skill or mode instead.

Calibration

examples/calibration.md shows a sized S answer, an M packet, and an L progress packet with their budgets applied. Match their density, not their subjects.