latex-compile-qa

WILLOSCAR 的头像作者 WILLOSCAR

编译一个 LaTeX 项目并运行基本的 QA(缺少引用、bib 错误、损坏的引用),生成 `latex/main.pdf` 和构建报告。**触发器**:latex 编译、构建 PDF、LaTeX 错误、缺少引用、编译PDF、引用错误。**使用条件**:已有 `latex/main.tex`(通常来自 `latex-scaffold`),需要确认可编译并输出失败原因报告。**如果**:则跳过:还没有LaTeX脚手架(先跑`latex-scaffold`)。**网络**:无。**Guardrail**:编译失败也落盘`output/LATEX_BUILD_REPORT.md`;不做“内容改写”,只做编译/QA。

📖 中文导读:编译一个 LaTeX 项目并运行基本的 QA(缺少引用、bib 错误、损坏的引用),生成 `latex/main.pdf` 和构建报告。**触发器**:latex 编译、构建 PDF、LaTeX 错误、缺少引用、编译PDF、引用错误。**使用条件**:已有 `latex/main.tex`(通常来自 `latex-scaffold`),需要确认可编译并输出失败原因报告。**如果**:则跳过:还没有LaTeX脚手架(先跑`latex-scaffold`)。**网络**:无。**Guardrail**:编译失败也落盘`output/LATEX_BUILD_REPORT.md`;不做“内容改写”,只做编译/QA。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: latex-compile-qa description: | Compile a LaTeX project and run basic QA (missing refs, bib errors, broken citations), producing latex/main.pdf and a build report. Trigger: latex compile, build PDF, LaTeX errors, missing refs, 编译PDF, 引用错误. Use when: 已有 latex/main.tex(通常来自 latex-scaffold),需要确认可编译并输出失败原因报告。 Skip if: 还没有 LaTeX scaffold(先跑 latex-scaffold)。 Network: none. Guardrail: 编译失败也要落盘 output/LATEX_BUILD_REPORT.md;不做“内容改写”,只做编译/QA。

LaTeX Compile + QA

Compile the LaTeX project and produce a PDF (when the toolchain is available), plus a short build report.

This step is deterministic; if compilation fails, record actionable diagnostics rather than guessing.

Inputs

  • latex/main.tex
  • citations/ref.bib

Outputs

  • latex/main.pdf (if compilation succeeds)
  • output/LATEX_BUILD_REPORT.md (recommended)

Workflow

  1. Run a LaTeX build (e.g., latexmk) if available.
  2. Fix missing packages, missing bib entries, and unresolved references.
  3. Record remaining issues in a build report.

Quality checklist

  • Either latex/main.pdf exists, or output/LATEX_BUILD_REPORT.md explains why compilation failed.
  • For arxiv-survey-latex deliverables: latex/main.pdf is >= 8 pages and has no undefined citations/references (strict gate).

Script

Quick Start

  • python .codex/skills/latex-compile-qa/scripts/run.py --help
  • python .codex/skills/latex-compile-qa/scripts/run.py --workspace <workspace_dir>

All Options

  • See --help (inputs/outputs are taken from the unit runner when used via pipeline)

Examples

  • Compile + produce report:
    • python .codex/skills/latex-compile-qa/scripts/run.py --workspace <ws>

Notes

  • Uses latexmk -xelatex -bibtex when available.
  • Always writes output/LATEX_BUILD_REPORT.md (success or failure).
  • Report includes page count + warning summary when available.

Troubleshooting

Common Issues

Issue: latexmk not found

Symptom:

  • Build report says “latexmk not found in PATH”.

Causes:

  • LaTeX toolchain is not installed.

Solutions:

  • Install a TeX distribution that includes latexmk.
  • If you can’t install tools, still use latex-scaffold to generate latex/main.tex and compile elsewhere.

Issue: Build fails with bib/ref errors

Symptom:

  • Report shows missing citations/refs or BibTeX errors.

Causes:

  • citations/ref.bib missing/miswired, or draft contains invalid cite keys.

Solutions:

  • Ensure latex/main.tex points to ../citations/ref.bib (or the correct relative path).
  • Ensure all citation keys exist in citations/ref.bib.

Recovery Checklist

  • Read output/LATEX_BUILD_REPORT.md tail for the first actionable error.
  • Confirm latex/main.tex exists and bibliography path is correct.