slide-excellence

幻灯片卓越性审查

对讲座幻灯片进行全面的多维审查。多个 Agent 分别分析文件，然后综合结果。

我该选择哪种幻灯片审查技能？

• /slide-excellence（此技能）——多 Agent 并行审查（视觉 + 教学法 + 校对，并按需加入 TikZ / 一致性 / 内容实质审查）。最适合教学前或发布前检查。
• /visual-audit——单一视角，仅检查布局 / 溢出 / 字体 / 间距。速度快。
• /pedagogy-review——单一视角，检查叙事 / 先备知识 / 示例推导 / 符号。
• /proofread——单一视角，检查语法 / 错别字 / 溢出 / 术语。
• /qa-quarto——对 Beamer ↔ Quarto 的一致性进行对抗式审查（批评者与修复者循环）。
• /devils-advocate——提出 5-7 个尖锐质疑，不进行完整审查。

重要说明： 此协调器会根据条件进行调度——只启动能对给定文件产生有效结果的子 Agent。对于不含 TikZ 的文件，它不会运行 tikz-reviewer；对于没有对应版本的幻灯片，它也不会运行 quarto-critic。

第 1 步：识别文件

从 $ARGUMENTS 中解析文件名。在 Quarto/ 或 Slides/ 中解析路径。

确定文件类型：

• .tex → Beamer
• .qmd → Quarto
• .md → Markdown 幻灯片

第 2 步：预检——检测条件

启动任何 Agent 之前，先探测文件以确定哪些审查适用：

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

报告检测结果：

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)

第 3 步：检查领域审查器是否已自定义（对 .tex 为必需）

在对 .tex 文件启动内容实质审查 Agent 之前，请确认 .claude/agents/domain-reviewer.md 已针对本项目完成自定义。发布版本中的 domain-reviewer 是一个模板——未经修改直接运行，只会给出“是否说明了假设？”之类的泛泛反馈，而非真正的领域审查。

检测启发式（符合以下任一项即视为仍是模板）：

• 文件中任意位置包含标记词元 AUTO-DETECT-TEMPLATE-MARKER（该词元存在于随附模板中；自定义时会将其移除或替换）。检测采用子字符串匹配——标记可以跨行。
• 包含任何 `` 或 [Customize: ...] 占位符（两种形式都会检查）。
• 五个审查视角与随附模板中的措辞完全相同（与 v1.3.0 标签中的 .claude/agents/domain-reviewer.md 比较——如果没有任何行发生变化，则仍是模板）。

如果存在模板标记：

⚠️  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).

在此停止并返回这些选项——此技能在分叉的上下文中运行，无法等待回答。不要对未自定义的模板运行 domain-reviewer；用户选择标志后再重新调用。

第 4 步：并行运行审查 Agent

仅启动符合条件的 Agent：

始终运行（针对幻灯片 .tex 或 .qmd）：

• Agent A：视觉审查（slide-auditor） 检查溢出、字体一致性、方框疲劳、间距和图像。当设置了 $qa_report 时（文件为 .qmd，或 .tex 有对应的 Quarto 文件），将其传入——其中包含测量得到的溢出数据和屏幕截图；如果无法运行 slide-qa，请在摘要中说明。 保存至：quality_reports/[FILE]_visual_audit.md。

• Agent B：教学法审查（pedagogy-reviewer） 检查 13 种教学法模式、叙事、节奏和符号。 保存至：quality_reports/[FILE]_pedagogy_report.md。

• Agent C：校对（proofreader） 检查语法、拼写错误、一致性、学术质量和引文。 保存至：quality_reports/[FILE]_proofread_report.md。

按条件运行：

• Agent D：TikZ 审查（tikz-reviewer）——仅当 has_tikz > 0 时运行。 基于测量的碰撞审计（贝塞尔曲线、间距、边界和边距）。 保存至：quality_reports/[FILE]_tikz_review.md。

• Agent E：内容一致性审查（quarto-critic）——仅当文件有对应文件（has_tex_pair 或 has_qmd_pair）时运行。 比较帧数、环境一致性以及 .tex ↔ .qmd 之间的内容差异。有 $qa_report 时将其传入。 保存至：quality_reports/[FILE]_parity_report.md。

• Agent F：R 代码审查（r-reviewer）——仅当 has_r == true 时运行。 检查内嵌 R 代码块或引用脚本中的代码是否正确。 保存至：quality_reports/[FILE]_r_review.md。

• Agent G：实质内容审查（domain-reviewer）——.tex 必须运行，.qmd 可选，且受第 3 步限制。 使用 5 视角框架检查领域内容是否正确。 保存至：quality_reports/[FILE]_substance_review.md。

**去重：**如果本次会话中这些技能之一已为此文件生成报告（例如先运行了 /proofread），且该报告比文件更新，则复用该报告，并列出复用的报告——此技能在分叉的上下文中运行，无法暂停并询问。若要强制重新审查，请将旧报告移出 quality_reports/（或修改幻灯片，使其时间戳更新），然后重新调用。

第 5 步：汇总综合摘要（归纳类型化发现）

这是一个扇出 → 归约流程（orchestrator-protocol.md）：每个 Agent 都会按共享架构返回 FINDINGs 和 SCORECARD（orchestration-schemas.md），此步骤会汇总类型化评分卡，而不是逐份目测报告。总体质量评分根据 CRITICAL/MAJOR/MINOR 数量总和确定是否通过门槛。（条件调度意味着，跳过的审查视角不会产生发现，而不是以零分计入平均值。）

仅包含实际运行的 Agent 对应的章节。

# 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

第 6 步：报告令牌/时间预算

完成后，打印已启动的内容：

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).

标志参考

标志	效果
--skip-substance	不启动 Agent G（domain-reviewer）。若尚未自定义 domain-reviewer.md，此选项会很有用。
--acknowledge-template-domain-reviewer	仍使用未经自定义的 domain-reviewer；这表示你接受实质内容审查会比较笼统。
--fast	启动单个综合 Agent 直接读取文件，而不是并行启动多个子 Agent。成本更低，但审查不够全面。

质量评分标准

评分	严重（blocker）	主要	含义
优秀	0	0	可供展示
良好	0	1-5	优先修改主要问题（门槛会将此情况判定为 REVISE）
需要改进	0-5	6 个及以上，或存在任何严重问题	需要大幅修改——只要还有严重问题，门槛就会阻止通过
较差	6 个及以上	任意数量	需要大幅重构

无论其他数量如何，任何严重问题都会阻止通过——这与 orchestration-schemas.md §3 中的门槛判定条件相同。

为什么条件式分派很重要

无法产出有用结果的审阅者会浪费 token，也会损害信任：不含 TikZ 的演示文稿交给 tikz-reviewer 审阅时不会有任何结果；没有对应文件时，quarto-critic 无从比较；未定制的 domain-reviewer 则只会给出“是否陈述了假设？”之类的通用反馈，作者很快就会对此置之不理。只启动文件实际用得上的审阅视角。

发现经过验证，而不只是写出来（v2.5）

此技能的审阅者会依据机器检查的规范输出发现，详见 finding-schema.json。报告必须是 JSON 数组。

在投入审阅工作前，先对测试框架进行冒烟测试——如果一次运行分派了多个审阅者，最终却无法写出有效报告，那么整轮工作都白费了：

echo '[]' | python3 scripts/validate-findings.py

审阅者 Agent 只能读取，因此由此技能写入文件。对于每位审阅者的最终回复：将文字报告保存到此技能中该审阅者对应的报告路径；将其结尾处的 fenced json 代码块复制到临时文件，并在验证时填入 ID：

python3 scripts/validate-findings.py --fill-ids block.json > <report>.json.tmp \
  && mv <report>.json.tmp <report>.json || rm -f <report>.json.tmp   # exit 0 required; a failed run keeps no file
python3 scripts/validate-findings.py --check-quotes <report>.json   # each quote must be the file's own text (orchestration-schemas.md §1)

如果审阅者没有返回 json 代码块，或代码块未通过验证，则表示尚未完成审阅：根据验证器的错误文本重新分派一次，然后将该审阅视角报告为缺失，而不是在没有它的情况下继续归并。

此规范要求的内容及其原因：

• rule——违反的文档规则或标准。未引用规则的发现只是观点，而观点不能作为提交的门槛。
• failing_case——主张不成立的具体配置，或缺失假设的准确内容。*“这里可以写得更清楚”*无法通过验证。
• id = sha1("<file>:<line>:<locus>")——具有确定性，因此不同轮次间可以精确去重，也能核查两次未通过规则，而不只是凭感觉判断。
• mechanical——仅当修复不会改变结果时才设为 true（拼写错误、交叉引用、格式、标签）。估计目标、假设、规范、推断程序、样本定义或报告措辞一律不得设为 true：这些问题应交还研究人员处理。

在验证之前，先依据 orchestration-schemas.md §7 中的各审阅视角证据要求和**“不计入”筛选条件进行筛选，避免已知误报进入裁决环节。验证环节采用倾向于反驳的原则**，并为每项发现设置 verdict（审阅者不设置此字段）：只有 verdict: "confirmed" 的发现会保留；无法依据证据确认的内容会被删除，而不是降级为警告。