Slide Excellence

Slide Excellence Review

Run a comprehensive multi-dimensional review of lecture slides. Multiple agents analyze the file independently, then results are synthesized.

Which slide-review skill do I want?

• /slide-excellence (this skill) — multi-agent fanout (visual + pedagogy + proofread, plus TikZ / parity / substance conditionally). Best for pre-teaching or pre-release checks.
• /visual-audit — single lens, layout/overflow/font/spacing only. Fast.
• /pedagogy-review — single lens, narrative/prerequisites/worked-examples/notation.
• /proofread — single lens, grammar/typos/overflow/terminology.
• /qa-quarto — adversarial Beamer ↔ Quarto parity (critic-fixer loop).
• /devils-advocate — 5-7 pointed challenges, not a full review.

Important: this orchestrator does conditional dispatch — it only spawns the subagents that can actually produce useful output for the given file. It does not run tikz-reviewer on a file with zero TikZ, or quarto-critic on a deck without a counterpart.

Step 1: Identify the File

Parse $ARGUMENTS for the filename. Resolve path in Quarto/ or Slides/.

Determine the file type:

• .tex → Beamer
• .qmd → Quarto
• .md → Markdown slides

Step 2: Pre-flight — Detect Conditions

Before spawning any agent, probe the file to determine which reviews make sense:

FILE="$resolved_path"

# Has TikZ diagrams?
has_tikz=$(grep -c '\\begin{tikzpicture}' "$FILE" 2>/dev/null); has_tikz=${has_tikz:-0}

# For .qmd: is there a paired .tex in Slides/?
has_tex_pair="false"
if [[ "$FILE" == *.qmd ]]; then
  base="$(basename "$FILE" .qmd)"
  # Common Beamer suffixes: _Topic, _Lecture, exact match
  for candidate in "Slides/${base}.tex" "Slides/Lecture${base}.tex"; do
    if [ -f "$candidate" ]; then
      has_tex_pair="true"
      tex_pair="$candidate"
      break
    fi
  done
fi

# For .tex: is there a paired .qmd in Quarto/?
has_qmd_pair="false"
if [[ "$FILE" == *.tex ]]; then
  base="$(basename "$FILE" .tex)"
  for candidate in "Quarto/${base}.qmd" "Quarto/${base#Lecture}.qmd"; do
    if [ -f "$candidate" ]; then
      has_qmd_pair="true"
      qmd_pair="$candidate"
      break
    fi
  done
fi

# Measure the Quarto render once — the file itself, or a .tex file's Quarto pair.
# The report goes to Agents A and E. slide-qa exits 0 (clean) or 1 (a finding:
# overflow, clipped content, or a broken asset) with a fresh report, 2 if it could
# not run (it deletes old reports first).
qa_report=""; qa_target=""
if [[ "$FILE" == *.qmd ]]; then qa_target="$FILE"
elif [ "$has_qmd_pair" = "true" ]; then qa_target="$qmd_pair"; fi
if [ -n "$qa_target" ]; then
  quarto render "$qa_target" >/dev/null 2>&1
  "${SLIDE_QA_PYTHON:-python3}" scripts/slide-qa.py "$qa_target"
  if [ $? -ne 2 ]; then
    qa_report="quality_reports/audits/slide-qa/$(basename "$qa_target" .qmd)/report.md"
  fi
fi

# Has R code chunks or referenced R scripts?
has_r="false"
if grep -qE '```\{r|source\(.*\.R\)' "$FILE" 2>/dev/null; then
  has_r="true"
fi

Report the detection:

File:         path/to/file.tex
Type:         Beamer (.tex)
TikZ blocks:  3
Quarto pair:  Quarto/Lecture2.qmd (found)
R chunks:     none
Slide QA:     quality_reports/audits/slide-qa/Lecture2/report.md (or: could not run — reason)

Step 3: Domain-reviewer customization check (MANDATORY for .tex)

Before spawning the substance-review agent on a .tex file, verify .claude/agents/domain-reviewer.md has been customized for this project. The ship-state domain-reviewer is a template — running it unmodified produces generic "are assumptions stated?" feedback, not real domain review.

Detection heuristic (any of these → still template):

• Contains the marker token AUTO-DETECT-TEMPLATE-MARKER anywhere in the file (present in the shipped template; removed/replaced when customized). Detection is a substring match — the marker can span lines.
• Contains any <!-- Customize: ... --> or [Customize: ...] placeholder (both forms are checked).
• The five lenses are identical to the shipped template's wording (diff against .claude/agents/domain-reviewer.md on the v1.3.0 tag — if zero lines changed, it's still template).

If the template marker is present:

⚠️  domain-reviewer.md has not been customized for your field.

Running it in its shipped state produces generic checks ("are assumptions
stated?") rather than field-specific review. Options:

  1. Customize .claude/agents/domain-reviewer.md — replace the 5 lenses
     with checks for your field (the file's EXAMPLES block shows two
     disciplines to copy from).
  2. Run slide-excellence with --skip-substance to proceed without the
     substance-review agent. Other reviewers still run.
  3. Run slide-excellence with --acknowledge-template-domain-reviewer to
     proceed anyway (you'll get generic feedback from the substance agent).

Stop here and return these options — this skill runs in a forked context and cannot wait for an answer. Do not run domain-reviewer on the uncustomized template; the user re-invokes with the flag they choose.

Step 4: Run Review Agents in Parallel

Spawn only the agents whose conditions hold:

Always-on for slides (.tex or .qmd):

• Agent A: Visual Audit (slide-auditor) Overflow, font consistency, box fatigue, spacing, images. When $qa_report is set (a .qmd, or a .tex with a Quarto pair), pass it — measured overflow plus screenshots; if slide-qa could not run, say so in the summary. Save: quality_reports/[FILE]_visual_audit.md.

• Agent B: Pedagogical Review (pedagogy-reviewer) 13 pedagogical patterns, narrative, pacing, notation. Save: quality_reports/[FILE]_pedagogy_report.md.

• Agent C: Proofreading (proofreader) Grammar, typos, consistency, academic quality, citations. Save: quality_reports/[FILE]_proofread_report.md.

Conditional:

• Agent D: TikZ Review (tikz-reviewer) — only if has_tikz > 0. Measurement-based collision audit (Bézier, gaps, boundaries, margins). Save: quality_reports/[FILE]_tikz_review.md.

• Agent E: Content Parity (quarto-critic) — only if the file has a counterpart (has_tex_pair or has_qmd_pair). Frame count comparison, environment parity, content drift between .tex ↔ .qmd. Pass $qa_report when there is one. Save: quality_reports/[FILE]_parity_report.md.

• Agent F: R Code Review (r-reviewer) — only if has_r == true. Code correctness for any embedded R chunks or referenced scripts. Save: quality_reports/[FILE]_r_review.md.

• Agent G: Substance Review (domain-reviewer) — MANDATORY for .tex, OPTIONAL for .qmd, GATED by Step 3. Domain correctness via the 5-lens framework. Save: quality_reports/[FILE]_substance_review.md.

De-duplication: if one of these skills already produced a report for this file in the current session (e.g. /proofread ran first), reuse that report when it is newer than the file and list which reports were reused — this skill runs in a forked context and cannot stop to ask. To force a fresh pass, move the old report out of quality_reports/ (or touch the deck so it is newer) and re-invoke.

Step 5: Synthesize Combined Summary (reduce typed findings)

This is fan-out → reduce (orchestrator-protocol.md): each agent returns FINDINGs + a SCORECARD in the shared schema (orchestration-schemas.md), and this step stacks the typed scorecards rather than re-reading each report by eye. The Overall Quality Score is the gate predicate over summed CRITICAL/MAJOR/MINOR counts. (Conditional dispatch means a skipped lens contributes no findings, not zeros to average.)

Only include sections for agents that actually ran.

# Slide Excellence Review: [Filename]

**File:** [path]
**Type:** [Beamer / Quarto / Markdown]
**Detected:** TikZ=N | pair=[path or none] | R=[yes/no]
**Agents spawned:** [A, B, C, D, G] (skipped: E [no pair], F [no R])

## Overall Quality Score: [EXCELLENT / GOOD / NEEDS WORK / POOR]

| Dimension | Critical (`blocker`) | Major | Minor | Score/10 |
|-----------|----------|--------|-----|-----|
| Visual/Layout | | | | |
| Pedagogical | | | | |
| Proofreading | | | | |
| TikZ (if ran) | | | | |
| Substance (if ran) | | | | |

### Critical Issues (Immediate Action Required)
### Major Issues (Next Revision)
### Recommended Next Steps

Step 6: Report Token/Time Budget

After completion, print what was spawned:

Spawned N agents[; token usage: actual figure, if the harness reports it].
For cost-conscious reviews, run individual subagent skills directly
(/proofread, /visual-audit, /pedagogy-review).