---
name: beamer-deck
description: "Create an academic presentation as a LaTeX Beamer source and reviewed PDF with an original theme. Use when the requested deliverable is a conference, seminar, or lecture deck in Beamer. Not for PowerPoint or RevealJS; use $pptx or $quarto-deck."
allowed-tools: Bash(latexmk*), Bash(xelatex*), Bash(pdflatex*), Bash(biber*), Bash(bibtex*), Bash(mkdir*), Bash(ls*), Bash(R*), Bash(Rscript*), Bash(uv:*), Read, Write, Edit, Task
argument-hint: "[topic, content-path, or project-name]"
skill-dependencies: [latex, project-deck]
---

# Beamer Deck Skill

> Generate academic Beamer presentations with original themes, rhetoric-driven structure, and multi-agent review. Internalises Scott Cunningham's rhetoric framework and implements an adversarial review workflow.

## Purpose

Create polished, zero-warning Beamer decks for academic contexts: seminars, conference talks, teaching lectures, and working decks for coauthors. Every deck gets a custom theme, assertion-driven titles, and parallel review by rhetoric and graphics sub-agents.

**NOT for project status updates** — use `project-deck` for those.

## When to Use

- Academic seminar presentations
- Conference talks (15–45 min)
- Teaching lectures (undergraduate or PhD)
- Working decks for coauthors or supervisors
- Any presentation that needs rhetoric discipline and visual quality

---

## Critical Rules

1. **Build artifacts go to `out/`, PDF stays in the source directory.** Use the `latex` pre-flight to install the fail-closed canonical `.latexmkrc`; never hand-write a partial config or copy block. Use `latex` for compilation and engine resolution.
2. **Python:** Always use `uv run python`. Never bare `python`, `python3`, `pip`, or `pip3`.
2. **Fix ALL warnings.** Overfull hbox, underfull hbox, overfull vbox, underfull vbox — no matter how small. Parse the `.log` file. Recompile until clean.
3. **Titles are assertions, not labels.** "Distance increases abortion rates" — not "Results". Every frame title states a claim.
4. **One idea per slide.** Not a guideline. A law. If a slide has two ideas, split it.
5. **Use the unified template.** Always use `\usepackage[<institution>]{user-beamer}` from `templates/beamer/`. Options: `preset-a`, `preset-b`, `preset-c`, `preset-d`, `plain`. Never use default Beamer themes (Warsaw, Madrid, etc.) as-is, and never create one-off preambles. See [`templates/beamer/README.md`] for available custom commands and how to add institutions.
6. **Code-first figures.** Generate figures via R or Python scripts before inserting. Never use placeholder images. **Always save the script alongside the figures** — never generate a figure without preserving the code that created it.
7. **If a `.bib` file is used, validate it.** Cross-reference all `\cite{}` keys against the bibliography file. See `bib-validate` for the full protocol.
8. **Never define parameterized TikZ styles inside a frame.** `#` inside a Beamer frame body is consumed by the frame parser before TikZ sees it, producing `Illegal parameter number` errors that cascade and resist all downstream fixes. Define ALL `\tikzset{...}` and `.style={..., #1}` entries in the preamble; use them inside frames. See [`../shared/tikz-rules.md`](../shared/tikz-rules.md) Rule 11.

---

## Rhetoric Principles

Full framework (Three Laws, MB/MC, Aristotelian Triad, Narrative Arc, Pyramid Principle, Devil's Advocate): [`../shared/rhetoric-principles.md`](../shared/rhetoric-principles.md)

Scott's original essay: `resources/academics/scott-cunningham/MixtapeTools/presentations/rhetoric_of_decks.md`

---

## Quality Scoring

Apply numeric quality scoring using the shared framework and skill-specific rubric:

- **Framework:** [`../shared/quality-scoring.md`](../shared/quality-scoring.md) — severity tiers, thresholds, verdict rules
- **Rubric:** [`references/quality-rubric.md`](references/quality-rubric.md) — issue-to-deduction mappings for this skill

Start at 100, deduct per issue found, apply verdict. Compute the score in Phase 7 and report it in the final output.

## Context-Specific Guidance

See [`../shared/rhetoric-principles.md`](../shared/rhetoric-principles.md) for the full Aristotelian Triad framework. Context-specific Ethos/Pathos/Logos balance and adjustments are applied in Phase 2 based on audience type (academic seminar, conference talk, teaching lecture, working deck).

---

## Workflow: 7 Phases

```
You (orchestrator)
├── Phase 1: Gather context        (direct)
├── Phase 2: Design structure       (direct)
├── Phase 3: Build deck             (direct)
├── Phase 4: Fix all warnings       (direct)
├── Phase 5: Rhetoric review        (sub-agent — Explore)
├── Phase 6: Graphics review        (sub-agent — Explore)  ← parallel with Phase 5
└── Phase 7: Apply & finalise       (direct)
```

### Phase 1: Gather Context (Direct)

Read project files, content sources, and audience brief. Ask the user clarifying questions:

- **Audience**: Who is this for? (seminar, conference, teaching, coauthors)
- **Duration**: How long is the talk?
- **Content source**: Paper draft? Notes? Existing slides? Code output?
- **Special requirements**: Specific figures, institutional branding, language?

Check for existing `.bib` files in the project. If citations are needed, note this for Phase 3.

### Phase 2: Design Structure (Direct)

1. **Choose rhetoric balance** based on audience (see table above)
2. **Outline slide sequence** with assertion titles — write each title as a claim
3. **Plan narrative arc** — consult [`docs/reference/talk-design.md`](../../docs/reference/talk-design.md) for format-specific arcs (empirical, structural, theory, descriptive) and audience calibration
4. **Choose institution option** for `user-beamer` — colours and fonts are set by the template
5. **Identify figures needed** — which need to be generated via code?

Present the outline to the user for approval before building.

### Phase 3: Build Deck (Direct)

1. **Generate figures first** — run R/Python scripts, save to `figures/`
2. **Write `.tex` file** using the unified template: `\documentclass[aspectratio=169,11pt]{beamer}` + `\usepackage[university]{user-beamer}` (or other institution option). Use `\fbinstitute` and `\fbemail` for metadata. Custom commands: `\contribcard`, `\phasecircle`, `\accentbox`, `\highlightbox`, `standoutframe` environment.
3. **Use 16:9 aspect ratio** (already in the documentclass above)
4. **Install the canonical `.latexmkrc`** through the `latex` pre-flight if it is missing; classify any divergent existing config before migration
5. **Compile using `latex`** — this handles missing packages, font conflicts, citation key mismatches, and stale cache automatically
6. **If using citations**: add `\addbibresource{references.bib}` or `\bibliography{}` as appropriate

### Phase 4: Fix All Warnings (Direct)

After `latex` resolves errors, address remaining **warnings** (which autofix does not fix):

1. Parse `out/*.log` for overfull/underfull hbox/vbox warnings
2. Fix every single one — adjust text, resize figures, tweak `\parbox`, etc.
3. Recompile
4. Repeat until the log is clean

**Circuit breaker — do not spiral.** If the same compile error persists after **3 different fix attempts**, STOP. Do not try a fourth approach. Instead:

1. Stop editing the `.tex` file.
2. Quote the exact error line from the `.log`.
3. List the 3 approaches tried and why each failed.
4. Ask the user how to proceed.

What counts as "the same error": any error that persists at the same line family after a fix (e.g., `Illegal parameter number` moving from line 568 to 572 is still the same error — that is the diagnostic signature in tikz-rules.md Rule 11). A fresh Overfull on a different slide after fixing the first is a *new* error — reset the counter.

The cost of stopping is 2 minutes; the cost of spiraling is an hour of edits that progressively obscure the original cause. This rule overrides "recompile until clean" — zero tolerance for warnings does not mean infinite attempts on the same fix.

**"Compilation success does not mean visual success."** Also check for silent visual errors:
- TikZ: shape constraints forcing label misplacement, coordinate misalignment. **If the deck contains TikZ diagrams**, run the 6-pass verification from [`../shared/tikz-rules.md`](../shared/tikz-rules.md) — compute Bezier depths, check gaps, verify label fit, check shape boundary clearance.
- matplotlib/ggplot: axis labels cut off, legend obscuring data, text sizing. **If figures use curved arrows (`arc3`)**, compute Bézier positions using the helper functions in `../shared/tikz-rules.md` § Matplotlib Extension — never guess where curves pass. Check label-to-shape clearance (Boundary Rule) and use anchor-based centering for text pairs.
- **PDF visual inspection**: Run `uv run python scripts/pdf-to-images.py <deck>.pdf` to convert pages to images, then inspect each image for text overflow, element overlap, font readability, and alignment issues that are invisible in the log

### Phase 5: Rhetoric Review (Sub-Agent — Explore)

Launch a sub-agent to review the `.tex` file against 7 criteria: narrative arc, MB/MC balance, title quality, one-idea-per-slide, transitions, Aristotelian balance, and pyramid principle.

Full prompt template: [`references/review-prompts.md`](references/review-prompts.md) § Rhetoric Review

### Phase 6: Graphics Review (Sub-Agent — Explore)

Launch **in parallel with Phase 5**. Reviews TikZ diagrams, figure sizing, table formatting, colour consistency, typography, and numerical accuracy.

Full prompt template: [`references/review-prompts.md`](references/review-prompts.md) § Graphics Review

### Phase 7: Apply and Finalise (Direct)

1. Read both reviewer reports
2. Incorporate feedback — prioritise Critical and Needs Work items
3. Recompile
4. Verify zero warnings in the log
5. **If using a `.bib` file**: validate all `\cite{}` keys resolve correctly (check log for `Citation .* undefined`). See `bib-validate` for the full cross-referencing protocol.
6. If significant changes were made, loop back to Phase 5 for another review round
7. **Compute quality score** — read `references/quality-rubric.md`, log all issues from Phases 4-6, compute score and verdict
8. Confirm final PDF is in the source directory (copied from `out/` by `.latexmkrc`)

---

## Reference Palettes

Three starting palettes (Professional, Energetic, Academic) in both LaTeX and CSS formats: [`../shared/palettes.md`](../shared/palettes.md)

Use as inspiration — always create an original palette for each deck.

---

## Output Checklist

A completed deck directory should contain:

```
project/
├── deck.tex              # Main Beamer file (uses user-beamer.sty)
├── deck.pdf              # Compiled PDF (copied from out/ by .latexmkrc)
├── .latexmkrc            # Canonical build config
├── out/                  # Build artifacts only
├── figures/              # Generated figures (if any)
│   ├── figure_1.png
│   └── ...
├── scripts/              # R/Python scripts that generated figures (if any)
│   ├── figure_1.R
│   └── ...
└── references.bib        # Bibliography (if citations used)
```

- [ ] PDF compiles with zero warnings
- [ ] All frame titles are assertions
- [ ] One idea per slide
- [ ] Narrative arc: Problem → Investigation → Resolution
- [ ] Rhetoric review completed (Phase 5)
- [ ] Graphics review completed (Phase 6)
- [ ] If `.bib` used: all `\cite{}` keys validated (see `bib-validate`)
- [ ] Quality score computed and reported

---

## Cross-References

| Skill | When to use instead/alongside |
|-------|-------------------------------|
| `project-deck` | For project status updates (supervisor meetings, coauthor handoffs) |
| `latex` | **Default compiler** — used in Phase 3 for error resolution and citation audit |
| `latex` | For manual compilation config details, `.latexmkrc` setup, engine selection |
| `proofread` | For post-hoc review of text quality in the deck |
| `bib-validate` | For thorough bibliography cross-referencing when citations are used |
| `literature` | For finding and verifying citations to include |
| `quarto-deck` | For HTML presentations (teaching, informal talks) instead of PDF |
| `quarto-course` | For full course websites with multiple lectures, exercises, and navigation |

**Scott's full rhetoric essay:** `resources/academics/scott-cunningham/MixtapeTools/presentations/rhetoric_of_decks.md`
**Scott's deck generation prompt:** `resources/academics/scott-cunningham/MixtapeTools/presentations/create_deck_prompt.md`
**Scott's example decks:** `resources/academics/scott-cunningham/MixtapeTools/presentations/examples/`