Explain Diff
Overview
Create a single self-contained HTML page that explains a code change with clear background, intuition, a structured walkthrough of the code changes, and an interactive quiz. Write with the clarity and flow of Martin Kleppmann, and favor concrete examples, diagrams, and callouts.
Workflow
- •
Gather context
- •Inspect the change and the surrounding code paths to understand how the system works before and after.
- •Identify the main behavioral change, key data flows, and any user-visible impact.
- •
Draft the content
- •Background: Provide a deep, beginner-friendly overview first, then a narrower background directly relevant to the change.
- •Intuition: Explain the essence of the change with toy examples and reusable diagram families.
- •Code: Walk through the change at a high level, grouping related modifications for clarity.
- •Quiz: Write five medium-difficulty multiple-choice questions that require real understanding, with immediate feedback.
- •
Build the HTML
- •Output a single HTML file that includes all CSS and JavaScript inline.
- •Use a table of contents and clear section headers on one long page (no tabs).
- •Provide responsive styling for mobile.
- •Use HTML-based diagrams (divs, lists, tables) and avoid ASCII diagrams.
- •Add callouts for key concepts, definitions, and edge cases.
- •
Save location and naming
- •Save the file outside the repo at
/tmp/explanation-YYYY-MM-DD-<slug>.html. - •Use today’s date and a short, descriptive slug derived from the change.
- •Save the file outside the repo at
Output checklist
- •Single self-contained HTML file with inline CSS/JS
- •Table of contents
- •Sections: Background, Intuition, Code, Quiz
- •Interactive multiple-choice quiz with feedback
- •Diagrams rendered with HTML/CSS (no ASCII)
- •Callouts for key points and edge cases
- •Saved in
/tmpwith date-based filename