Create Lecture

• One idea per slide. This is not a guideline. It is the law.
• Too many points → zero points retained
• Dense text → nothing read
• Complex charts → confusion, not insight

Law 3: Slides Serve the Spoken Word

Slides are not documents. They are visual anchors for what you say:

• Focal point for attention
• Memory hook for retention
• Evidence supporting your claim
• Structural marker in the argument

If your slides can be understood without you speaking, you have written a document and called it a presentation.

RHETORIC OF DECKS PRINCIPLES

Titles as Assertions (Not Labels)

Slide titles carry the argument. They are claims, not labels.

Weak: "Results" | "Methods" | "Literature Review"

Strong: "Treatment increased distance by 61 miles on average" | "We exploit county-level variation in clinic closures" | "Prior work ignores the supply-side margin"

Teaching context: Even in lectures, titles should make declarative claims:

• "Trade Openness Reduces Conflict Duration" (not "Trade and Conflict")
• "Identification Requires Exogenous Variation" (not "Identification Strategy")
• "The DID Estimator Assumes Parallel Trends" (not "Difference-in-Differences")

If someone reads only your slide titles in sequence, they should understand the argument.

MB/MC Equivalence: Information Density Balance

Optimal rhetoric equalizes the marginal benefit to marginal cost ratio across slides:

$$\frac{MB_1}{MC_1} = \frac{MB_2}{MC_2} = \cdots = \frac{MB_n}{MC_n}$$

Overloaded slides (MB/MC too low):

• Text running into the footer
• Multiple competing ideas
• Charts with too many series
• Audience gives up before extracting value

Underloaded slides (MB/MC too high):

• Single word that could support a sentence
• Wasted opportunity to reinforce the point
• Audience attention captured but not used

The audit: For each slide ask: "If I added one more element, would the benefit justify the cognitive cost? If I removed one element, would I lose more than I'd gain in clarity?"

Narrative Arc: Problem → Investigation → Resolution

Every presentation tells a story in three acts:

1. Problem (Tension): Establish the status quo, introduce the disruption/challenge/question, make the audience feel the problem
2. Investigation (Development): Show what you tried, present what you learned, build the logical case
3. Resolution (Release): Deliver the insight, show implications, provide the call to action

This is not optional. It is how human brains process information.

The Pyramid Principle

Lead with the conclusion. Then support it.

Structure:

1. Here's what I'm going to tell you (the claim)
2. Here's the evidence for it
3. Here's why it matters

Not: Background → more background → complication → analysis → finding (finally).

Humans are not suspense novels. We want the punchline, then understand why it's true.

No Bullet Lists: Find Structure Instead

Bullets are a confession of defeat. They say "I couldn't figure out the relationship between these ideas, so I'm just listing them."

Structure hiding in bullets:

• A sequence: first, then, finally (use a flow chart)
• A contrast: on one hand, on the other (use a comparison table or split slide)
• A hierarchy: the main point and supporting details (use indentation or visual nesting)
• A causal chain: because of X, we see Y (use a diagram or timeline)

Find the structure. Make it visible. Use layout, not bullets.

Teaching exception: Axioms, properties, or step-by-step derivations require lists for clarity. When using lists, ensure they have a structural relationship (not just a grab-bag of items).

One Message Per Chart, No Chartjunk, Direct Labels

Charts are arguments, not decorations. Every chart must answer: What am I supposed to conclude from this?

Principles:

• One message per chart: If you can't explain what it proves in one sentence, it's too complex
• Remove chartjunk: No 3D effects, excessive gridlines, decorative elements, or stock aesthetics
• Label directly: No legends requiring eye movement back to axes
• Use color to highlight the key comparison
• Title states the claim: Not "Figure 1: Regression Results" but "Treatment increased adoption by 23 percentage points"

The Devil's Advocate Slide

Before presenting your argument, present its strongest critique:

Format:

• "A skeptic would say..."
• "Here's what could go wrong..."
• "The strongest objection is..."

Then your response, mitigation, and acknowledgment of residual risk.

This accomplishes:

1. Ethos: You've done the hard thinking
2. Preemption: You've addressed objections before they're raised
3. Credibility: You're not hiding from problems

The paradox: Admitting weakness builds credibility. The presenter who says "this approach has three significant limitations" is more trusted than one claiming perfection.

CONSTRAINTS (Non-Negotiable)

1. Check existing lectures FIRST — read READING_LIST.md, relevant existing .qmd files, SESSION_LOG.md, and the Exercise Plan from the case file (Phase A.4 output). Also read _rules/exercise-strategy.md for format taxonomy and timing rules

2. Motivation before formalism — every theoretical section starts with a real-world puzzle or fact 2b. Retrieval recap (L02+): Every lecture after L01 must open with a 2-3 min retrieval exercise testing recall of the previous lecture's key concepts (Quick Poll or "write down 3 takeaways without notes"). This comes BEFORE the recap slide — students retrieve first, then the instructor provides the bridge. See exercise-strategy.md Rule T6. 2c. Data-linked Quick Polls: Before showing motivation or anchoring figures, insert a 1-2 min Quick Poll asking students to predict what the data will show. Target: 1-2 per lecture. See exercise-strategy.md Rule T7.

3. Worked example within 2 slides of every definition — show the concept applied

4. Identification strategy always explicit — treatment, outcome, controls, key assumption 4b. (V7.17) Every slide showing regression coefficients MUST include one of:

   • A brief identification note: "Identified via [IV/DiD/RDD]: [instrument/treatment]"
   • A caveat: "Descriptive correlation — not a causal estimate"
   • A structural model note: "From logit/probit model — coefficients are log-odds, not marginal effects" The research brief tags each coefficient as CAUSAL/DESCRIPTIVE/STRUCTURAL. R2 must use these tags. Showing coefficients without ID context is a D1 deduction (-2 pts).

5. Max 2 colored boxes per slide (alertblock, exampleblock). Minimum per lecture: use alertblock for 2-3 key definitions/results and exampleblock for 2-3 worked examples or case studies. This ensures Pattern 9 (box hierarchy) is present — distinguishing definition vs. example vs. neutral content visually.

6. Pause whitelist (P1-P5) — pauses are FORBIDDEN by default. In dual-output QMDs, use . . . (dot-space-dot-space-dot, on its own line) instead of \pause. A pause is allowed ONLY if it matches one of these five situations:

   • P1 — Question → Answer reveal: Socratic Q on one overlay, answer appears after pause
   • P2 — Predict → Data reveal: "What do you think happened?" → pause → show figure/result
   • P3 — Step-by-step derivation: Building a worked example incrementally (e.g., 2SLS stage 1 → pause → stage 2 → pause → interpretation)
   • P4 — DA critique → response: "A skeptic would say..." → pause → "But the evidence shows..."
   • P5 — Dense slide split: Slide has >5 bullets or >150 words of resolved content — pause to reduce cognitive overload

   Explicitly BANNED pause locations (even if they "feel natural"):

   • Between regular bullet points in a list
   • After slide titles or before source lines
   • Between table rows
   • On transition/bridge slides
   • On exercise slides (students need full instructions at once)
   • Before/after key takeaway text
   • Between items students need to see together for comparison

   Self-test: For every . . . in the draft, ask: "Does this make the audience think 'what comes next?' before seeing the answer?" If no → delete it. There is NO numeric pause target — quality over quantity.

7. Transition slides at major conceptual pivots

8. Thread at least 1 running empirical application throughout the lecture

9. Page budget: frame count is the primary metric. For a 90-minute lecture:

   • Count unique frames: ## headings → target 35–40 (this is the binding constraint)
   • Count . . . pauses → compute pause_ratio = pauses / frames
   • Under P1-P5 whitelist (Rule 6), expect ratio 0.2–0.5. This means pause-adjusted pages ≈ 42–60, which is correct.
   • Raw PDF page count will be higher (Beamer creates one page per overlay) — this is expected and NOT a problem.
   • If frames > 40: merge slides. If frames < 35: content may be too thin.
   • Do NOT artificially add pauses to inflate page counts.

10. Work in batches of 10 slides — share for feedback, don't bulk-dump

11. MANDATORY CITATIONS: Every paper listed in the syllabus for this lecture's topic MUST appear in the slides. Read conflict_MA.pdf (the syllabus) and extract the required papers for the lecture topic. Include proper \source{Author (Year)} attributions on relevant slides. This is a strict rule — zero-citation lectures are unacceptable. After drafting, run a citation check (see Post-Creation Checklist).

12. Heading convention: Always use ## Slide Title to create frames. Never use raw \begin{frame}{Title} unless [fragile] is needed (for pgfplots/verbatim). Mixing conventions causes inconsistency and makes maintenance harder.

13. Time estimates on interactive slides: Every quiz, exercise, discussion, or group-work slide MUST include an estimated duration in the slide title or content, e.g. ## Exercise: Identify the Endogeneity (8 min) in the slide heading. NEVER use HTML comments (<!-- -->) — they render as visible text in Beamer PDF. This enables accurate lecture-time estimation in the compile-slides assessment. Regular content slides don't need explicit time tags — they default to ~2 min/slide.

14. MANDATORY EMPIRICAL FIGURES: For every empirical paper given deep treatment (8+ slides), include at least one data visualization — a TikZ scatter plot, time series, bar chart, or schematic figure showing the paper's key finding visually, not just as a coefficient table. Use \source{Dataset (Year)} attribution. This is non-negotiable: lectures about empirical papers without figures feel abstract and AI-generated.

15. Devil's Advocate is mandatory: Every lecture MUST have at least 2 explicit "Skeptic's Objection" or "Devil's Advocate" slides that present the strongest criticisms of the main argument, each followed by a response. Typical pattern: one DA after the deep-treatment paper, one DA in the synthesis/recent advances section. No exceptions — the rubric scores 4 pts for 2+ DA slides, only 2 pts for 1.

16. Current events anchor: Every lecture MUST reference at least one real-world event or case from the last 5 years to ground the theory in current relevance. Abstract-only lectures fail the "Why should I care today?" test.

17. Paper citations: Full author names, never abbreviations: NEVER use shorthand like "MV14", "MSS04", "C-H" on slides — these are for internal notes. Always write "Miguel, Satyanath and Sergenti (2004)" not "MSS04". In \source{} tags: "Maystadt and Verwimp (2014)" not "MV14". Short forms acceptable ONLY in slide titles after full introduction on a previous slide.

Source Citation Convention

Do NOT put a source tag on every slide. This is a lecture, not a paper.

• Data figures and tables: proper citation required (dataset name, year, author)
• Diagrams adapted from a source: "Inspired by Author (Year)" or "Adapted from Author (Year)"
• Direct quotes: cite with author, year, and page number
• Specific empirical claims (coefficients, sample sizes): cite the paper
• General framework slides (explaining a theory): cite the paper ONCE in the section title or first slide of that section. Do NOT repeat on every subsequent slide in the same section.
• Teaching materials: NEVER cite as "teaching materials." Cite the published book or paper instead. Add a general acknowledgment slide at the end if desired.
• Figures: include a source line in the figure itself (bottom-left). Do NOT also add a \source{} tag on the QMD slide — one citation per figure is enough.
• Everything else: no source tag needed. The lecture context makes authorship clear.

18. Content height: Frame Content Budget (see converter_rules.md §20): Count ALL content after all \pause commands resolve. Pauses don't save space — the final overlay must fit. If content exceeds the budget, split into two frames. Text running into the Metropolis footer is a hard failure.

Budget by frame type:

19. TikZ text integration: Place text ABOVE tikzpicture or use columns environment. Never place free-form text after a tikzpicture — it overlaps. Use \node for annotations on diagrams. See converter_rules.md Rule 22.
20. Real-world examples density: Each major section (3-5 slides) should open with a concrete story, country case, or current data point — not a paper summary. Students engage with "In 2021, Ethiopia's Tigray war displaced 2.5 million people" more than "Forced displacement has significant welfare effects."
21. Content gap limit (T1 enforcement): No section may have more than 8 consecutive content frames without an active element (exercise, Socratic Question with audience pause, or Quick Poll). If a paper requires 10+ slides of deep treatment, insert a Socratic Q or data-linked Quick Poll in the middle. The orchestrator checks this in R2-audit.
22. Recent Advances must be THEMATIC, not sequential paper parades. Group 2-3 papers per slide by shared insight or debate (e.g., "Identification Debate", "Micro-Level Evidence", "Policy Interventions"). Each thematic slide uses two-column layout with a red takeaway line. NEVER create 5-6 consecutive one-paper-per-slide summaries — this is the #1 structural deficiency found in Batch 1 blind scoring. The section MUST include at least one active element (Socratic Q or discussion prompt) to avoid back-loading 7+ content slides with no interaction. Max 3-4 slides total for Recent Advances.
23. Coefficient consistency (cross-slide verification): When a paper's empirical results appear in BOTH a worked example and a summary table (or on multiple slides), the numbers MUST be identical OR explicitly labeled as different specifications with table/column references (e.g., "Table 3, Col. 2: -0.29" vs "Table 3, Col. 4: -0.40"). Internal numerical contradictions (e.g., "-0.14" on one slide and "-0.15" on another for the same coefficient) are a HARD scoring failure. The create-lecture agent must grep the draft for all numbers appearing in \textbf{} or table cells and verify consistency before Phase 6.

• CRITICAL: Worked example arithmetic verification. After writing ANY worked example with numbers, the create-lecture agent MUST re-derive every calculation step and verify the result. Example: if war destroys 10% of a $100 pie, the remaining pie is $90. If A wins with p=0.6, A's expected war payoff is 0.6 × $90 = $54, NOT 0.6 × $100 = $60. The bargaining range is then [$54, $64], NOT [$40, $60]. Getting reservation values wrong in a bargaining example contradicts the entire model.
• CRITICAL: Worked example consistency. If a worked example computes β_IV = γ/π, the result MUST match the 2SLS coefficient stated on any other slide. In just-identified IV, β_2SLS = reduced form / first stage EXACTLY.
• Unit consistency: If a coefficient is -0.029 (one unit GDP growth → 0.029 change in conflict probability), the interpretation must match the scale. A 5pp GDP decline × -0.029 = 0.145pp, NOT 14.5pp. Confusing proportions and percentage points is a HARD FAILURE.
• Model-appropriate interpretation: State the model type (OLS, logit, probit, 2SLS) on the methods slide. If logit/probit: interpret via marginal effects at means, NOT by multiplying raw coefficients by ΔX. If IV: state LATE interpretation explicitly. If F-statistic is cited: give the exact number and compare to Stock-Yogo threshold (~10 for 10% maximal bias). Never write "above the weak instrument threshold" for F<10.

24. Mechanical pause ban (see Rule 6 whitelist P1-P5): This rule is enforced via the whitelist in Rule 6. Every . . . must match P1-P5. If it doesn't, delete it. No exceptions.
25. Exercise parameter independence: Exercises MUST use different numbers than worked examples. If a worked example computes 0.044 × 17 = 0.75, the exercise must use a DIFFERENT coefficient, a DIFFERENT country, or a DIFFERENT variable — not the same calculation with the same inputs. Students should practice the METHOD on new data, not copy the example. Specifically:

• Change at least 2 of: coefficient value, variable name, country/context, time period
• The exercise should require genuine computation, not recall of a result shown 2-3 slides earlier
• If the exercise references lecture slides for parameters, it must also introduce NEW parameters not shown on those slides
• Self-test: Would a student who memorized the worked example get full marks without understanding the method? If yes → redesign the exercise.

26. Formula and notation explanation (HARD RULE): Every symbol, variable, or subscript in a formula MUST be defined on the same slide where it first appears. If a slide shows β_IV = γ/π, it must also say what β_IV, γ, and π represent. Pattern: formula on top/left, then a bullet list defining each symbol, then interpretation. Never assume students know what a symbol means from context. This applies to:

• Regression equations (define Y, X, β, ε, subscripts)
• Game theory payoffs (define each player's strategy space and payoff components)
• Bargaining models (define p, c_A, c_B, and what the bargaining range endpoints mean)
• Indices (define F for fractionalization, P for polarization, with the formula components)
• Self-test: Cover the text and look only at the formula. Can a student who missed last lecture understand every symbol? If not, add definitions.

27. TikZ and Mermaid diagram sizing (HARD RULE): Diagrams must fill the available slide space, not cluster in a corner.

• TikZ in Beamer: Use scale=1.0 or higher. Diagrams should span at least 80% of \textwidth. Use \begin{center} wrapper. Never use scale=0.5 or smaller — if the diagram is too complex, simplify it rather than shrinking.
• Mermaid in RevealJS: Mermaid diagrams render at their natural size. Ensure they are the primary content of the slide, not a sidebar to text. If a Mermaid diagram is on a slide, it should be the visual focus.
• Diagram-first layout: On slides with both text and a diagram, the diagram comes FIRST (top or left column), text supports it. Never bury a diagram below 5 bullets.
• Fill the slide: A diagram slide should look like 60-70% visual, 30-40% text. If the diagram is small and there's empty white space, the diagram needs to be larger or the slide needs restructuring.

28. Exercise debrief frames (HARD RULE): Every exercise MUST be followed by a dedicated debrief slide within 1-2 frames. The debrief summarizes the key insight, shows the "instructor's answer," or synthesizes what pairs/groups discussed. Pattern:

• Quick Poll / Whole-Class Vote: Debrief = reveal correct answer + explain why (can be on same slide via pause if total fits within Frame Content Budget)
• Think-Pair-Share / Pair Problem: Debrief = separate slide with 2-3 key points the instructor highlights
• Small Group Discussion: Debrief = separate slide synthesizing the main arguments
• Individual Reflection: Debrief = transition slide connecting student thought to next content
• NEVER embed the answer via \pause on the exercise slide itself — this violates Frame Content Budget (the exercise setup + answer exceeds the 4-line budget). The debrief is a separate pedagogical moment.
• Self-test: After placing each exercise, verify: "Is there a slide within 2 frames that unpacks the exercise?" If not, add one.

29. [UNVERIFIED] tag enforcement (HARD RULE): Every empirical claim (statistic, coefficient, date, percentage) that cannot be verified against a paper in the Literature/ folder, a Zotero entry, or an API download MUST be tagged [UNVERIFIED] inline. This tag:

• Signals to the domain-reviewer (R4) that the claim needs checking
• Prevents unverified numbers from being scored as "accurate" in D1.2
• Is removed ONLY after verification (by the literature-manager or domain-reviewer)
• Threshold: More than 3 unverified claims caps D1 at 20/25 (cannot earn full marks with uncertain factual foundation)
• Claims from the research brief that are marked [INDEPENDENTLY VERIFIED] do NOT need the tag
• Claims paraphrased from a book not available for checking (e.g., popular science books) ALWAYS get the tag

30. Source tag coverage minimum (HARD RULE): At least 80% of content slides (excluding section dividers, exercise slides, and title/ending slides) MUST have a \source{} tag. The selective citation convention (Rule 17b) still applies — not every slide needs one. But a lecture where only 44% of content slides have sources fails the credibility test. Pattern:

• Section-opening slides: cite the primary paper for that section
• Data/empirical slides: cite the dataset or paper
• Theory mechanism slides: cite the originating paper (once per section, not every slide)
• Exercise/discussion slides: no source needed
• Summary/concept check slides: no source needed
• Self-test: Count \source{ occurrences and divide by content slide count. If <80%, add sources to the highest-value missing slides.

31. Mermaid parity: SVG pre-render for complex TikZ (HARD RULE): Not all TikZ diagrams can be faithfully represented in Mermaid. When a TikZ diagram uses features Mermaid cannot replicate (mathematical plots, overlapping curves, number lines with precise positioning, continuous functions), the RevealJS block MUST use a pre-rendered SVG image instead of a degraded Mermaid flowchart. Procedure:

• During R2, identify TikZ diagrams that use \draw plot, \fill[pattern], coordinate math, or axis-like constructs
• For each such diagram, add a manifest entry: PRE-RENDER: L{XX}_data/fig_name.svg
• The R3a data-visualizer (or a separate pre-render step) generates the SVG from the TikZ source
• The RevealJS block uses ![Description](L{XX}_data/fig_name.svg){width="80%"} instead of a Mermaid approximation
• A Mermaid flowchart that pretends to be a number line, distribution plot, or time-series curve is WORSE than an SVG — it misleads students about the visual structure
• Mermaid is appropriate for: decision trees, causal chains, categorization trees, flow processes, simple comparison diagrams

32. PRE-RENDER markers must be invisible (HARD RULE): PRE-RENDER instructions are pipeline-internal metadata. They MUST appear ONLY inside HTML comments (<!-- PRE-RENDER: ... -->), NEVER in student-visible slide content. If a PRE-RENDER SVG has not yet been generated, the RevealJS block should show a descriptive italic placeholder (*[Conceptual diagram: bargaining range number line]*) — NOT the raw PRE-RENDER instruction text. The R3a data-visualizer or a pre-render step replaces these with actual ![](path){width="80%"} embeds. Any raw PRE-RENDER text visible to students is a HIGH audit finding.

33. Figure embedding after R3a (HARD RULE): After R3a (data-visualizer) generates figures, an R3.5 embedding step MUST replace all placeholder text in the QMD with actual image embeds:

• Beamer: \includegraphics[width=\textwidth]{L{XX}_data/fig_name.pdf}
• RevealJS: ![Description](L{XX}_data/fig_name.svg){width="85%"}
• If SVG/PNG versions exist in L{XX}_data/ alongside PDFs, RevealJS MUST use SVG (browsers cannot render inline PDFs)
• The placeholder pattern *[Figure placeholder: ...]* followed by a raw path string is NEVER acceptable in final output
• Self-test: grep for Figure placeholder and \texttt{.*includegraphics} — both must return zero matches after R3.5

34. Devil's Advocate visual requirement (HARD RULE): The DA section (typically 4 slides: skeptic1 + response1 + skeptic2 + response2) creates the longest text-only run in most lectures. To prevent this:

• At least ONE slide in the DA section must contain a visual element (diagram, comparison table, or figure)
• Good candidates: claim-vs-evidence comparison table, endogeneity diagram showing the critique visually, a "what the critique assumes vs. reality" two-column visual
• The response slides are the natural place for visuals — they can show data or diagrams that counter the critique
• 4+ consecutive text-only slides anywhere in the lecture is a HIGH audit finding under the visual density check

35. Empirical grounding table (proper format): Empirical lectures: At least one deep-treatment paper must have a proper descriptive statistics table showing sample size (N), variable names, means, and standard deviations — like Table 1 in empirical papers. A factoid table with numbers from different sources does NOT qualify. Theoretical lectures (e.g., L01): Include an empirical grounding table from a SINGLE authoritative dataset (e.g., UCDP/PRIO Armed Conflict Dataset summary: N conflicts by type, mean duration, regional distribution, time period covered). This anchors theory in real data and earns 2/2. The key requirement: numbers must come from ONE coherent source with stated N and time coverage — not miscellaneous factoids from 4 different reports.

DOMAIN-SPECIFIC RULES: TEACHING LECTURES

Teaching lectures differ from seminars because:

• Clarity > Compression: More text per slide is acceptable because students take notes from slides
• Repetition is OK: Learning requires revisiting concepts multiple times
• Progressive reveal: Use \pause (Beamer overlays) for step-by-step derivations and concept building
• Definitions get their own slides with block environments: use \begin{alertblock}{Title} for key definitions/results and \begin{exampleblock}{Title} for worked examples/case studies. This visual distinction (Pattern 9: box hierarchy) helps students immediately identify content type.
• "Why does this matter?" should appear frequently to maintain motivation

Teaching Structure Pattern

1. Recap & Today's Plan (2-3 slides): Establish puzzle early
2. Motivation: Puzzle / Stylized Facts (3-5 slides): The "why" before the "what"
3. Theoretical Framework (5-8 slides): Concepts with definitions, worked examples
4. Paper 1: Deep Treatment (8-12 slides): Identification by slide 6
5. Paper 2: Complementary Evidence (5-8 slides): Show extension/generalization
6. Recent Advances & Extensions (3-5 slides, THEMATIC — see Rule 22 below)
7. Discussion & Applications (2-3 slides)
8. Concept Check / Summary (2-3 slides): Test student understanding
9. Looking Ahead (1 slide): Bridge to next lecture

Key timing: For a 50-75 minute lecture, pace ~0.5-1 minute per content slide (accounting for \pause overlays and discussion pauses).

Diagrams for Theoretical Content (HARD RULE)

Every theoretical mechanism or concept MUST have its own diagram. Text-only theory slides are the #1 structural failure mode — they make lectures feel like paper compilations rather than teaching.

Mechanism decomposition rule: When a theory has N key mechanisms (e.g., 3 causes of bargaining failure, 5 reasons for conflict), EACH mechanism gets:

1. Its own dedicated slide with a diagram showing the causal chain or logic
2. A brief explanation supporting the visual (not replacing it)
3. Where possible, a short exercise or concrete example illustrating that specific mechanism

The goal is pedagogical depth per mechanism, not cramming all mechanisms onto one slide. Good transitions between mechanism slides create the narrative thread.

Diagram types by content:

• Causal mechanisms → flow diagram (TikZ arrows showing cause → effect)
• Categorizations/taxonomies → tree diagram or radial layout
• Bargaining/game theory → number line, payoff matrix, or decision tree
• Empirical relationships → annotated scatter or stylized curve
• Processes/cycles → cycle diagram with labeled arrows
• Comparisons → two-column visual contrast

Density rule: No more than 3 consecutive content slides without a diagram or data figure. If you find yourself writing 4+ text-only slides in a row, stop and add a visual.

RevealJS parity: Every TikZ diagram in Beamer MUST have an equivalent visual in RevealJS (SVG, Mermaid, or structured HTML/CSS). Plain-text bullet fallbacks are NOT acceptable — they lose the pedagogical value of the diagram.

CRITICAL: QMD Formatting Rules (Read rules/converter_rules.md First!)

Brace Balance

• EVERY \textcolor{X}{ MUST close with } — this is the #1 compilation failure
• Pattern: \textcolor{highlight}{\textbf{Key:} text} — note BOTH closing braces
• After writing each batch, verify brace balance per line

Frame Headers

• ## Slide Title → auto-generates \begin{frame}{Title}
• NEVER put ## Title before a raw \begin{frame}[fragile] — causes double-frame
• For fragile frames (pgfplots, verbatim): use raw \begin{frame}[fragile] WITHOUT ##

pgfplots (AVOID — use simple TikZ instead)

• Default to simple TikZ (\draw, \fill, \node, \foreach) for all charts. pgfplots (\begin{axis}) is a LAST RESORT for cases where axis scaling, log axes, or regression lines are essential and cannot be approximated.
• Why: pgfplots adds ~5s compile time per block, generates overfull warnings (hbox/vbox) that inflate the warning count, and requires [fragile] frames. Simple TikZ compiles instantly, produces zero overfull warnings, and works with ## Title frames.
• Hard limit: Max 1 pgfplots per lecture. If you need 2+ data charts, use TikZ \draw + \fill for bar charts, \foreach loops for scatter plots, and \node for annotations.
• If pgfplots is used: legend pos=north east (NOT upper right), must use \begin{frame}[fragile]{Title} WITHOUT ##

Source/Takeaway Commands

• \source{} and \takeaway{} are defined by converter preamble
• Do NOT redefine in YAML header-includes (causes duplicate definition error)
• The YAML header-includes should only add EXTRA packages/commands not in preamble

Sub-headers

• ### Title → \textbf{Title} (auto-converted)
• Use for in-slide sub-sections

Slide Space Usage

Slides should use the available space effectively:

• Use larger font sizes for key content (RevealJS default is often too small)
• Prefer fewer items per slide with larger text over cramming content
• Two-column layouts (:::: {.columns}) help fill horizontal space
• If a slide has >30% whitespace below content, either add a visual or split the content differently

TEMPLATE

YAML Header (Dual Output — v7.7)

All new lectures produce both RevealJS HTML (primary) and Beamer PDF (backup) from one QMD:

---