latex-check

What this skill does

# LaTeX/TikZ/Beamer Auditor

## Overview

A comprehensive auditing skill for LaTeX documents, including article/report/book classes, TikZ/PGF graphics, pgfplots visualizations, and Beamer presentations. All recommendations are grounded in official CTAN documentation and TeX best practices.

## Auto-Invoke Triggers

Use this skill when task mentions:
- "LaTeX check" or "TeX audit"
- "TikZ" or "pgfplots"
- "Beamer" or "slides"
- "compile errors" or "compilation issues"
- "aspectratio" or "16:9"
- "externalize" or "tikzexternalize"
- "latexmk" or "pdflatex"
- "biblatex" or "biber"
- "hyperref" or "cleveref"

## Scientific & Standards Foundation

This skill enforces best practices from:

1. **LaTeX Project Documentation** - Official LaTeX kernel and class documentation
2. **TikZ & PGF Manual** (tikz.dev) - Graphics and externalization library
3. **pgfplots Manual** (CTAN) - Data plotting best practices
4. **Beamer User Guide** (CTAN) - Presentation class guidelines
5. **hyperref Manual** (CTAN) - Package loading order and PDF metadata
6. **cleveref Manual** (CTAN) - Type-aware cross-referencing
7. **biblatex Manual** (CTAN) - Modern bibliography with biber backend
8. **microtype Manual** (CTAN) - Character protrusion and font expansion
9. **csquotes Manual** (CTAN) - Locale-aware quotation handling
10. **WCAG 2.1** - Web Content Accessibility Guidelines (for Beamer contrast)
11. **ChkTeX Documentation** - Semantic LaTeX linting
12. **latexmk Manual** (CTAN) - Automated multi-pass compilation

## Audit Scope

### 1. Document & Engine Configuration
- Document class detection (article, beamer, IEEEtran, etc.)
- Engine compatibility (pdfLaTeX, XeLaTeX, LuaLaTeX)
- Input encoding and font encoding
- Class options validation

### 2. Package Configuration
- Package loading order (critical for hyperref, cleveref)
- Package compatibility checks
- Required vs. optional packages
- Version-specific requirements

### 3. Cross-References & Hyperlinks
- hyperref loading position (near end of preamble)
- PDF metadata configuration
- cleveref integration (load after hyperref)
- Label prefix conventions (fig:, tab:, sec:, eq:)

### 4. Bibliography
- Modern biblatex + biber vs. legacy BibTeX
- Backend configuration verification
- Citation style consistency
- Toolchain completeness (pdflatex → biber → pdflatex)

### 5. TikZ/PGF & pgfplots
- TikZ library loading
- pgfplots compatibility level
- Data file separation for large plots
- Externalization setup and security
- Shell-escape requirements and warnings

### 6. Beamer Presentations
- Aspect ratio configuration (43, 169, 1610)
- Theme and color scheme consistency
- Overlay density analysis (≤5 per frame recommended)
- Frame content balance
- WCAG AA contrast compliance (≥4.5:1 normal, ≥3:1 large text)

### 7. Typography & Formatting
- microtype for improved typography
- Font selection and loading
- Page layout and geometry
- Quotation handling with csquotes

### 8. Linting & Code Quality
- ChkTeX semantic checks
- latexindent formatting
- Code organization and readability

### 9. Compilation Workflow
- latexmk usage and configuration
- Shell-escape security considerations
- Multi-pass compilation requirements
- Estimated compilation time

### 10. Accessibility
- Alternative text for figures (when feasible)
- Color-independent information encoding
- Contrast ratios for Beamer slides
- Logical document structure

## Audit Process

### Phase 1: Document Analysis

1. **Read the LaTeX source file(s)**
   - Main `.tex` file
   - Included files via `\input` or `\include`
   - Class files (`.cls`) if custom
   - Style files (`.sty`) if custom

2. **Extract metadata**:
   ```
   - Document class: \documentclass[options]{class}
   - Class options: aspectratio, fontsize, paper size, etc.
   - Engine hints: fontspec (XeLaTeX/LuaLaTeX), inputenc (pdfLaTeX)
   ```

3. **Parse preamble**:
   - List all `\usepackage{...}` commands in order
   - Extract package options
   - Note custom commands and environments

4. **Detect document type**:
   - Article/report/book → Standard academic document
   - Beamer → Presentation (trigger Beamer-specific checks)
   - IEEEtran/ACM/others → Conference/journal template

### Phase 2: Run Checklist Rules

Load rules from `checklists/latex_checklist.yml` and execute in order:

#### 2.1 Document Structure
- `class_detect`: Identify class and validate options
- `engine_detect`: Determine appropriate LaTeX engine
- `encoding_check`: Verify UTF-8 input and T1 font encoding (pdfLaTeX)

#### 2.2 Package Configuration
Execute in sequence:

1. **hyperref_order**: Verify hyperref loaded near end
   ```
   RULE: hyperref must come after most packages
   EXCEPTION: cleveref, glossaries must come after hyperref
   ```

2. **hyperref_metadata**: Check PDF metadata
   ```
   VERIFY: \hypersetup{pdftitle=..., pdfauthor=..., pdfsubject=..., pdfkeywords=...}
   ```

3. **cleveref_present**: If cross-refs detected, recommend cleveref
   ```
   DETECT: \ref{}, \label{} usage
   RECOMMEND: \usepackage{cleveref} after hyperref
   ```

4. **cleveref_order**: Verify cleveref loaded last
   ```
   RULE: cleveref must be one of the last packages
   EXCEPTION: Only microtype may come after
   ```

5. **bib_backend**: Check bibliography system
   ```
   PREFER: biblatex with backend=biber
   LEGACY: \bibliography{}, \bibliographystyle{} → flag for migration
   ```

6. **microtype_enabled**: Verify microtype for typography
   ```
   CHECK: \usepackage{microtype} present
   NOTE: Works with pdfLaTeX, XeLaTeX, LuaLaTeX
   ```

7. **csquotes_present**: Check quotation handling
   ```
   DETECT: ``, '', \"{}, etc. → recommend csquotes
   VERIFY: \usepackage{csquotes} after babel/polyglossia
   ```

8. **babel_polyglossia**: Language support
   ```
   pdfLaTeX: \usepackage[language]{babel}
   XeLaTeX/LuaLaTeX: \usepackage{polyglossia}
   ```

#### 2.3 TikZ & PGF
Execute if TikZ detected:

1. **tikz_present**: Confirm TikZ package and usage
   ```
   DETECT: \usepackage{tikz}, \begin{tikzpicture}
   ```

2. **tikz_libraries**: Verify library loading
   ```
   COMMON: positioning, arrows.meta, shapes, calc
   CHECK: \usetikzlibrary{...} before first use
   ```

3. **pgfplots_present**: Check pgfplots usage
   ```
   DETECT: \usepackage{pgfplots}, \begin{axis}
   ```

4. **pgfplots_compat**: Verify compatibility level
   ```
   REQUIRE: \pgfplotsset{compat=1.18} or compat=newest
   REASON: Enables modern features and behavior
   ```

5. **tikz_compile_cost**: Estimate compilation time
   ```
   COUNT: Number of tikzpicture environments
   ESTIMATE:
     - 1-5 figures: Low
     - 6-15 figures: Medium
     - 16-30 figures: High
     - 31+ figures: Very High
   RECOMMEND: Externalization if High or Very High
   ```

6. **externalize_detection**: Check externalization setup
   ```
   DETECT: \usetikzlibrary{external}, \tikzexternalize
   VERIFY: prefix=tikz-cache/ or similar
   ```

7. **externalize_shell_escape**: Verify shell-escape awareness
   ```
   IF externalization detected:
     REQUIRE: Compilation with -shell-escape
     WARN: Security implications (only trusted documents)
     RECOMMEND: latexmk -pdf -shell-escape document.tex
   ```

8. **tikz_naming**: Check for explicit figure naming
   ```
   RECOMMEND: \tikzsetnextfilename{descriptive-name}
   REASON: Reproducible cache names, easier debugging
   ```

#### 2.4 Beamer (if applicable)
Execute if `\documentclass{beamer}` detected:

1. **beamer_class**: Confirm Beamer detection
2. **aspect_ratio**: Check aspectratio option
   ```
   DEFAULT: 43 (4:3)
   MODERN: 169 (16:9 widescreen)
   OTHER: 1610 (16:10), 149 (14:9)
   RECOMMEND: 169 for contemporary displays
   ```

3. **frame_title**: Verify all frames have titles
   ```
   CHECK: \begin{frame}{Title} or \frametitle{Title}
   REASON: Structure, navigation, accessibility
   ```

4. **overlay_detection**: Count overlay specifications
   ```
   DETECT: \pause, <n->, \onslide<>, \only<>, etc.
   LOAD: lexicons/beamer_overlays.ym