---
name: explain-diff-ez
description: Use when the user asks for a rich, easy-to-scan explanation of a code change, diff, branch, or PR — especially when the reader wants something less "textbook" than dense prose. Produces a single self-contained interactive HTML artifact.
---

# Explain Diff (EZ)

Please make me a rich, interactive, but highly *scannable* explanation of the specified code change. The reader should be able to skim it in under a minute and get the gist, then dig into any section for depth — not read it top to bottom like a textbook.

## Language

- Default to the reader's stated or evident preferred language. If the user tells you they're not fluent in English (or asks in another language), write the **entire explanation** in that language — headings, body text, diagram labels, callouts, quiz questions and answers, everything except literal code/file paths/identifiers, which stay as-is since they're real artifacts from the codebase.
- If no language preference is evident, ask, or default to English.
- Never mix languages within a sentence — if writing in Thai, don't leave English explanatory clauses half-translated.
- **Write headings natively, not as translations.** When writing in a non-English language, do not compose headings in English first and translate them — calqued metaphors read as confusing "translation-ese" (e.g. "Safety Net" → "ตาข่ายนิรภัย" forces the reader to decode the metaphor twice). Instead:
  - Prefer headings that are a question the section answers ("ทำไม...", "...ทำงานยังไง") or a plain statement of what's inside — these read naturally in Thai, unlike English-style noun phrases.
  - Drop the metaphor and state the function directly: "Safety Net" → "test กันพลาด", "Code Walkthrough" → "เจาะโค้ดทีละส่วน".
  - Transliterate technical terms practitioners actually say aloud (test, validator, merge, deploy) rather than forcing formal native translations — but never embed them inside a translated metaphor.
- **The no-calque rule applies to body text too, not just headings.** Before finishing, reread the prose for phrases that only make sense if you back-translate them to English — e.g. "ไม่คลาดเคลื่อนทั้งสองทิศทาง" ("in both directions"), "สัญชาตญาณที่ผิด" ("wrong instinct") — and restate the actual meaning plainly ("ไม่หลวมกว่าและไม่เข้มกว่าของจริง", "หลายคนจะคิดแบบนี้เป็นอย่างแรก แต่สรุปแบบนั้นไม่ได้").
- **Untranslated jargon needs a plain-language escort.** Terms like false-positive, flaky, deterministic, mount: either replace with a plain description of what happens ("จับผิดเนื้อหาที่ถูกอยู่แล้ว" instead of "false-positive"), or keep the term but only where a glossary tooltip defines it. Never drop bare jargon into a sentence the reader can't unpack.

## Sections

- **TL;DR box** at the very top of *every* section (Background, Intuition, Code, and any subsection that runs long) — 3-5 short bullets stating the takeaway before the reader has to read the prose. This is not optional decoration; assume the reader may read *only* the TL;DR boxes and still come away with the right mental model.
- **Background**: Explain the existing system relevant to this change (explore surrounding code broadly for this). Include a deep background for beginners, marked skippable, then a narrower background directly relevant to the change.
- **Intuition**: Explain the core intuition — the essence, not full details. Use concrete toy examples and diagrams liberally.
- **Code**: High-level walkthrough of the changes, grouped/ordered for understanding, not file-by-file in diff order.
- **Quiz**: Five interactive multiple-choice questions, medium difficulty (need real understanding, not gotchas), with click-to-reveal correctness + feedback per choice. Choices must be balanced so the correct answer is not identifiable by form:
  - All choices in a question must be similar in length and specificity (within ~30% of each other) — never let the correct answer be the longest, most detailed, or most carefully hedged option.
  - Put explanations and reasoning in the per-choice feedback (shown only after answering), never in the choice text itself. Choice text states a claim; feedback explains why it's right or wrong.
  - Distractors must be plausible at the same level of specificity as the correct answer — reference real mechanisms, files, or terms from the codebase, not vague strawmen.

## Digestibility rules (this is the main difference from a plain writeup)

- **Prefer bullets over paragraphs.** Default to short bullet lists. Only use a flowing paragraph when the point genuinely requires connected reasoning that bullets would fragment awkwardly — and even then, keep it to 2-3 sentences.
- **Numbered step-lists for anything sequential** (an algorithm, a pipeline, "first X happens, then Y") — use a visually distinct numbered-step component, not prose narration of steps.
- **Collapsible `<details>` blocks for optional depth.** When a point has an interesting-but-non-essential aside (an edge case, a historical reason, a deep implementation detail), put it behind a `<details><summary>` toggle labeled with what's inside, so the core reading path stays lean and the curious reader can expand it.
- **Short section intros, not throat-clearing.** Get to the point in the first sentence of each section; skip meta-commentary about what you're about to explain.
- **One idea per bullet/paragraph.** If a bullet needs "and" to connect two separate claims, split it.

## Interactive comprehension aids

Build these with vanilla inline JS/CSS only (no external libraries — the artifact must be fully self-contained):

- **TL;DR-only mode (required).** A single fixed/prominent toggle button that collapses the whole page down to just the TL;DR boxes of every section, and expands back. A reader with two minutes presses it and still leaves with the right mental model. Make the button label self-explanatory (e.g. "อ่านเฉพาะสรุปสั้น" / "Read TL;DRs only").
- **Step-through diagrams (required for the main flow being explained).** For the most important sequential concept in the change (a pipeline, an algorithm, a request flow), build a diagram with Next/Back buttons where each step highlights the active part and swaps in a one-sentence caption for that step. Do NOT use auto-playing animation — the reader must control the pace. Keep it to one or two step-through diagrams per page; static diagrams remain fine for secondary concepts.
  - **Progressive reveal:** start by showing only the first node with its caption — never the full diagram at once, which overwhelms the reader before they've oriented. Each "Next" fades in the next node (and its connecting arrow) with a short CSS transition (~0.4s opacity + slight translate); "Back" fades them out. The caption should also cross-fade on step change rather than swapping instantly.
  - Hidden future nodes should reserve their layout space (hide via opacity, not display) so the diagram doesn't jump or reflow as steps appear.
  - Degrade gracefully: apply the hiding classes from JS only, so with JS disabled the full diagram is visible and readable as a static figure.
- **Before/after toggle (required when the change has a "correct vs broken" or "old vs new" contrast).** A clickable switch that flips a single example between two states (e.g. valid syntax → rendered result vs broken syntax → raw text), so the reader can compare interactively instead of reading two static panes side by side. If there's no meaningful contrast to show, skip it rather than forcing one.
- **Annotated code markers (use when a code block has 2+ noteworthy points).** Put small numbered markers (①②③) on the relevant lines of a code block; clicking/tapping a marker reveals a short explanation anchored right there. This replaces the pattern of a code block followed by a paragraph the reader must cross-reference. For a code block with only one point to make, a plain caption is fine.
- **Glossary tooltips (use for recurring technical terms).** Underline-dotted key technical terms (e.g. regex, frontmatter, orchestrator) so hover/tap shows a one-line definition in the reader's language. Define each term once in a shared JS map so the same term is consistent everywhere. Especially important when the reader is not fluent in English — the definition should be in their language even when the term itself stays in English.

Make every interactive element degrade gracefully: content must still be readable in logical order if JS somehow fails, and all controls need visible affordances (buttons that look like buttons), since readers won't discover invisible interactions.

## Format

- Output a single self-contained HTML file with inline CSS and JS. One long page with section headers and a table of contents at the top. No tabs for top-level structure.
- Responsive: usable on a phone. Interactive elements must work with tap, not just hover — anything hover-triggered needs a tap equivalent.
- Theme-aware: support both light and dark via `@media (prefers-color-scheme)` and `:root[data-theme]` overrides, since the artifact viewer's theme toggle must work correctly in both directions.
- Save the file in a global place outside the code repo, filename starting with today's date in `YYYY-MM-DD-` format, e.g. `/tmp/2026-01-12-explanation-<slug>.html`.
- Publish it as an Artifact (not just a local file) so the user gets a shareable link, unless they ask otherwise.

## Diagrams

- Reuse a small number of diagram families throughout (don't invent a new visual style per section):
  - A simplified UI mock, for explaining UI-visible changes.
  - A system/pipeline diagram showing data flow between components, with concrete example data.
  - A before/after split-pane or toggle for "what was written" vs "what the reader/user sees as a result."
- No ASCII diagrams — build diagrams from simple styled HTML/CSS (divs, flexbox), not `<pre>` art.
- For code blocks, always use `<pre>` tags. If using a custom styled div instead, it **must** have `white-space: pre-wrap` in its CSS. Before saving, scan every code block in the HTML source and confirm each has `white-space: pre` or `pre-wrap`.
- Use callout boxes for key concepts, definitions, and important edge cases — styled distinctly from TL;DR boxes so the reader can tell "summary" apart from "important warning" at a glance.

## Tone

- Write with clarity and warmth, not academic distance — closer to a sharp colleague explaining something over coffee than a spec document. Keep transitions between sections smooth even though the internal structure is bullet-heavy.