slide-excellence

スライドの総合レビュー

講義スライドを多角的に包括レビューします。複数のエージェントがファイルを個別に分析し、その後、結果を統合します。

どのスライドレビュー用スキルを使いますか？

• /slide-excellence（このスキル）— 複数エージェントによる並列レビュー（ビジュアル＋教育設計＋校正に加え、条件に応じて TikZ／整合性／内容も対象）。授業前や公開前のチェックに最適です。
• /visual-audit — レイアウト／はみ出し／フォント／間隔のみを対象とする単一の視点。高速です。
• /pedagogy-review — 論の展開／前提知識／例題／記法を対象とする単一の視点。
• /proofread — 文法／誤字／はみ出し／用語を対象とする単一の視点。
• /qa-quarto — Beamer と Quarto の整合性を敵対的に検証します（批評と修正を繰り返します）。
• /devils-advocate — 鋭い指摘を 5～7 件行います。包括的なレビューではありません。

重要： このオーケストレーターは条件に応じて処理を振り分けます。対象ファイルに対して有益な出力を実際に生成できるサブエージェントのみを起動します。TikZ が一切含まれないファイルに tikz-reviewer を実行したり、対になるファイルがないスライド資料に quarto-critic を実行したりすることはありません。

ステップ 1：ファイルの特定

$ARGUMENTS を解析してファイル名を取得します。Quarto/ または Slides/ 内のパスを解決します。

ファイルの種類を判定します。

• .tex → Beamer
• .qmd → Quarto
• .md → Markdown スライド

ステップ 2：事前確認 — 条件の検出

エージェントを起動する前にファイルを調べ、どのレビューが適切かを判定します。

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 ファイルで内容レビュー用エージェントを起動する前に、.claude/agents/domain-reviewer.md がこのプロジェクト用にカスタマイズされていることを確認します。配布時のドメインレビュアーはテンプレートです。変更せずに実行すると、実際のドメインレビューではなく、「前提条件は示されていますか？」といった一般的なフィードバックが生成されます。

検出方法（次のいずれかに該当する場合、まだテンプレートです）：

• ファイル内のどこかにマーカートークン AUTO-DETECT-TEMPLATE-MARKER が含まれている（配布テンプレートにあり、カスタマイズ時に削除または置換されます）。検出は部分文字列の照合です。マーカーが複数行にまたがっていても検出されます。
• `` または [Customize: ...] のプレースホルダーが含まれている（両方の形式を確認します）。
• 5 つの観点が、配布テンプレートの文言と同一である（v1.3.0 タグの .claude/agents/domain-reviewer.md と比較し、変更された行が 0 行なら、まだテンプレートです）。

テンプレートマーカーがある場合：

⚠️  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：レビューエージェントを並列で実行する

条件を満たすエージェントのみを起動します。

スライド（.tex または .qmd）では常に実行：

• エージェント A：ビジュアル監査（slide-auditor） はみ出し、フォントの一貫性、ボックスの多用、間隔、画像を確認します。$qa_report が設定されている場合（.qmd、または Quarto ペアがある .tex）、それを渡してください。測定したはみ出しとスクリーンショットを含めます。slide-qa を実行できなかった場合は、その旨を概要に記載してください。 保存先：quality_reports/[FILE]_visual_audit.md。

• エージェント B：教育的レビュー（pedagogy-reviewer） 13 の教育的パターン、ナラティブ、進行、記法を確認します。 保存先：quality_reports/[FILE]_pedagogy_report.md。

• エージェント C：校正（proofreader） 文法、誤字、一貫性、学術的な品質、引用を確認します。 保存先：quality_reports/[FILE]_proofread_report.md。

条件付き：

• エージェント D：TikZ レビュー（tikz-reviewer）— has_tikz > 0 の場合のみ。 測定に基づいて、重なり（ベジェ曲線、間隔、境界、余白）を監査します。 保存先：quality_reports/[FILE]_tikz_review.md。

• エージェント E：コンテンツの一致性（quarto-critic）— 対応するファイルがある場合（has_tex_pair または has_qmd_pair）のみ。 フレーム数の比較、環境の一致性、.tex ↔ .qmd 間のコンテンツのずれを確認します。$qa_report がある場合は渡してください。 保存先：quality_reports/[FILE]_parity_report.md。

• エージェント F：R コードレビュー（r-reviewer）— has_r == true の場合のみ。 埋め込み R チャンクまたは参照スクリプトのコードが正しいか確認します。 保存先：quality_reports/[FILE]_r_review.md。

• エージェント G：内容のレビュー（domain-reviewer）— .tex では必須、.qmd では任意、ステップ 3 の条件に従います。 5 つのレンズのフレームワークで、ドメインの正確性を確認します。 保存先：quality_reports/[FILE]_substance_review.md。

重複排除： このセッションで、これらのスキルのいずれかがこのファイルのレポートをすでに作成している場合（例：先に /proofread を実行した場合）、そのレポートがファイルより新しければ再利用し、再利用したレポートを列挙してください。このスキルはフォークされたコンテキストで実行されるため、停止して確認することはできません。新たにレビューを実行するには、古いレポートを quality_reports/ の外に移動する（または、デッキに touch して新しい日時にする）うえで、再度実行してください。

ステップ 5：統合概要をまとめる（型付き指摘を集約）

これは ファンアウト → 集約 です（orchestrator-protocol.md）。各エージェントは、共有スキーマ（orchestration-schemas.md）に従って FINDINGs と SCORECARD を返します。このステップでは各レポートを目視で読み直すのではなく、型付きスコアカードを積み上げます。Overall Quality Score は、CRITICAL／MAJOR／MINOR の合計数に対するゲート述語です。（条件付きディスパッチでスキップされたレンズは、指摘を返さず、平均の計算にゼロとして加算されることもありません。）

実際に実行されたエージェントのセクションのみを含めてください。

# 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	エージェント G（domain-reviewer）を起動しません。domain-reviewer.md をまだカスタマイズしていない場合に便利です。
--acknowledge-template-domain-reviewer	カスタマイズされていない domain-reviewer をそのまま使って続行します。内容レビューが一般的なものになることを了承したものとします。
--fast	並列サブエージェントの代わりに、ファイルを直接読む単一の統合エージェントを起動します。コストは低くなりますが、徹底度も下がります。

品質スコアの基準

スコア	Critical（blocker）	Major	意味
優秀	0	0	発表できる状態
良好	0	1-5	まず Major を修正してください（ゲートでは REVISE と判定されます）
要改善	0-5	6+、または Critical が 1 件以上	大幅な修正が必要です — Critical が残っている間、ゲートはブロックします
不良	6+	任意	大規模な再構成が必要です

ほかの件数にかかわらず、Critical の指摘が 1 件でもあればブロックされます。これは orchestration-schemas.md §3 と同じゲート述語です。

条件付きディスパッチが重要な理由

有用な出力を生成できないレビュー担当は、トークンと信頼を無駄にします。TikZ を含まないスライド資料に対する tikz-reviewer は何も返さず、対応するファイルがない quarto-critic には比較対象がなく、カスタマイズされていない domain-reviewer は、執筆者が無視するようになる一般的な「前提は明記されていますか？」というフィードバックを返します。そのファイルに適用できる観点だけを起動してください。

指摘事項は書き出すだけでなく検証されます（v2.5）

このスキルのレビュー担当は、 finding-schema.json に定められた機械検査可能な契約に従って指摘事項を出力します。レポートは JSON 配列です。

レビューに時間をかける前に、ハーネスのスモークテストを実施してください。レビュー担当を並行して起動した後、有効なレポートを書き出せなければ、レビュー全体が無駄になります。

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

レビュー担当のエージェントは読み取り専用なので、ファイルの書き出しはこのスキルが行います。各レビュー担当の最終回答について、散文形式のレポートをそのレビュー担当用のこのスキルのレポートパスに保存し、末尾のフェンス付き 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 とします。推定対象、仮定、仕様、推論手順、サンプルの定義、報告の文言には絶対に設定しないでください。これらは研究者に差し戻します。

検証の前に、 orchestration-schemas.md §7 の観点ごとの証拠要件と**「該当しない」フィルターを適用し、既知の誤検出が判定担当に届かないようにしてください。検証パスでは反証を優先**し、各指摘事項の verdict を設定します（レビュー担当は設定しません）。verdict: "confirmed" の指摘事項だけを報告します。根拠を示せないものは警告に格下げせず、除外してください。