latex-check

name	latex-check
description	Comprehensive LaTeX/TikZ/Beamer auditor. Validates document structure, package configuration, cross-references, bibliography setup, TikZ externalization, and Beamer presentations. Produces standards-backed reports with MWEs and compilation guidance.

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.yml patterns
   

5. overlay_density: Flag excessive overlays

   THRESHOLD: 5 overlays per frame
   IF count > 5:
     WARN: Over-complexity
     SUGGEST: Consolidate or split frame
   

6. frame_content_balance: Check frame content volume

   HEURISTIC: >20 lines of content → potentially overcrowded
   RECOMMEND: Split across multiple frames
   

7. contrast_check: Assess WCAG compliance

   ANALYZE: Theme colors (if standard theme)
   REFERENCE: lexicons/beamer_overlays.yml contrast guidelines
   WARN: Potential contrast failures
   RECOMMEND: Test with contrast checker
   

Phase 3: Optional Compilation Test

If user requests or document is problematic:

1. Invoke compilation (if code-capable helper available):

   COMMAND: latexmk -pdf -interaction=nonstopmode -halt-on-error document.tex
   IF externalization detected:
     ADD: -shell-escape flag
   

2. Parse compilation output:

   • Errors → severity: error
   • Warnings → severity: warn
   • Overfull/underfull boxes → severity: info

3. Check auxiliary files:

   • .log file for detailed errors
   • .bcf file for biblatex backend
   • .bbl file for bibliography compilation

Phase 4: Generate Outputs

4.1 Create Audit Report

Use templates/audit_report_template.md:

1. Fill executive summary:

   • Overall status (excellent/good/needs_improvement/critical_issues)
   • Count findings by severity
   • Highlight top 3-5 issues

2. Document analysis section:

   • Class, engine, packages
   • TikZ/Beamer specifics

3. Findings by category:

   • Group by checklist section
   • Include evidence (line numbers, code snippets)
   • Reference official documentation

4. Detailed findings:

   • Each finding with:
     • ID (from checklist)
     • Severity (error/warn/info)
     • Message
     • Evidence
     • Reference (CTAN manual, page number if applicable)
     • Fix recommendation

5. Compilation guidance:

   • Recommended command
   • Shell-escape notes
   • Estimated compilation time

6. MWE references:

   • Link to generated minimal working examples

4.2 Create Fix Plan

Use templates/fix_plan_template.md:

1. Priority 1 actions (errors):

   • Step-by-step fix instructions
   • Code snippets for corrections
   • Expected outcome

2. Priority 2 actions (warnings):

   • Recommended improvements
   • Impact explanation

3. Priority 3 actions (info):

   • Best practices
   • Optional enhancements

4. Package loading order:

   • Complete preamble template
   • Organized by category
   • Comments explaining order

5. Specialized fixes:

   • TikZ externalization setup (if needed)
   • Beamer aspect ratio and overlay fixes (if applicable)
   • Bibliography migration guide (if needed)

4.3 Generate JSON Output

Conform to schema/tex_audit_schema.json:

{
  "metadata": {...},
  "document": {...},
  "packages": {...},
  "tikz": {...},
  "beamer": {...},
  "findings": [...],
  "compilation": {...},
  "mwe_paths": [...],
  "summary": {...}
}

4.4 Create Minimal Working Examples

Generate MWEs for relevant fixes:

1. TikZ Externalization (if applicable):

   • Copy mwes/tikz_externalization.tex
   • Customize for user's specific setup

2. Beamer 16:9 with Overlays (if applicable):

   • Copy mwes/beamer_16_9_overlays.tex
   • Adapt to user's theme

3. Modern Bibliography (if BibTeX detected):

   • Copy mwes/modern_bibliography.tex
   • Show migration path

4. Best Practices Template:

   • Always provide mwes/best_practices_article.tex
   • Demonstrates complete modern setup

4.5 Provide Lint Configurations

1. ChkTeX configuration:

   • Copy lint/.chktexrc to project
   • Explain usage: chktex -v0 -l document.tex

2. latexindent configuration:

   • Copy lint/indentconfig.yaml to project
   • Explain usage: latexindent -l=indentconfig.yaml -w document.tex

Phase 5: Safeguards & Notes

1. Shell-escape warning:

   IF -shell-escape required:
     EMPHASIZE: Security implications
     NOTE: Only use with trusted documents
     EXPLAIN: Restricted shell escape in modern distributions
   

2. Package conflicts:

   IF known conflicts detected:
     WARN: Specific incompatibilities
     SUGGEST: Alternative approaches
   

3. Manual references:

   FOR each recommendation:
     CITE: Specific manual section
     PROVIDE: CTAN link or official documentation URL
   

4. Beamer accessibility:

   IF Beamer detected:
     NOTE: Contrast recommendations are WCAG 2.1 AA guidelines
     ACKNOWLEDGE: Theme customization may be needed
     PROVIDE: Contrast checking tools
   

Detection Rules Implementation

Package Loading Order

Correct order (with rationale):

% 1. ENCODING & FONTS (pdfLaTeX only)
\usepackage[utf8]{inputenc}    % UTF-8 input
\usepackage[T1]{fontenc}        % T1 font encoding

% 2. LANGUAGE
\usepackage[english]{babel}     % Or polyglossia for XeLaTeX/LuaLaTeX
\usepackage{csquotes}           % After babel

% 3. MATHEMATICS (early for other packages to use)
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{amsthm}

% 4. GRAPHICS & FLOATS
\usepackage{graphicx}
\usepackage{float}
\usepackage{caption}
\usepackage{subcaption}

% 5. TABLES
\usepackage{booktabs}
\usepackage{array}
\usepackage{multirow}

% 6. TIKZ (if needed)
\usepackage{tikz}
\usetikzlibrary{positioning,arrows.meta,shapes,calc}
\usepackage{pgfplots}
\pgfplotsset{compat=newest}

% 7. BIBLIOGRAPHY
\usepackage[backend=biber,style=authoryear]{biblatex}
\addbibresource{references.bib}

% 8. PAGE LAYOUT
\usepackage{geometry}

% 9. HYPERLINKS (near end!)
\usepackage[colorlinks=true,...]{hyperref}

% 10. CROSS-REFERENCES (after hyperref!)
\usepackage{cleveref}

% 11. TYPOGRAPHY (last!)
\usepackage{microtype}

Rationale:

• Encoding/fonts first: Affects character processing
• Language early: Affects hyphenation patterns
• Math early: Other packages may need math commands
• Graphics/tables: Independent, can be anywhere in middle
• TikZ: May use math, graphics facilities
• Bibliography: Needs to hook into referencing
• Hyperref late: Redefines many commands, needs others loaded first
• cleveref after hyperref: Needs hyperref's reference system
• microtype last: Fine-tunes final typography

TikZ Externalization Detection

IF \usetikzlibrary{external} present:
  CHECK for \tikzexternalize command
  VERIFY prefix setting
  COUNT tikzpicture environments
  ESTIMATE cache size

  IF count > 10:
    STRONGLY RECOMMEND externalization
  IF count 5-10:
    RECOMMEND externalization
  IF count < 5:
    NOTE: Optional, may not provide significant benefit

  ALWAYS WARN: Requires -shell-escape

Beamer Overlay Analysis

FOR each \begin{frame}...\end{frame}:
  COUNT occurrences of:
    - \pause
    - <n-> patterns (extract n)
    - \onslide<...>
    - \only<...>
    - \item<...>

  COMPUTE max overlay number for frame

  IF max > 5:
    WARN: Excessive overlays
    PROVIDE frame title/line number
    SUGGEST: Consolidation strategies

  ACCUMULATE global overlay statistics

Contrast Estimation (Beamer)

FOR standard Beamer themes:
  LOAD known color schemes
  ESTIMATE contrast ratios

FOR custom themes:
  WARN: Manual contrast checking required
  PROVIDE: Online contrast checker tools
  REFERENCE: WCAG 2.1 SC 1.4.3

ALWAYS NOTE:
  - Normal text: ≥4.5:1 (AA)
  - Large text (≥18pt): ≥3:1 (AA)
  - Don't rely solely on color

Example Usage Patterns

Pattern 1: Basic Article Audit

User: "Check my LaTeX document for issues"

Process:
1. Read document.tex
2. Detect class: article
3. Run document/packages/crossref/bib checks
4. Generate audit report
5. Provide fix plan
6. Include best_practices_article.tex as reference

Pattern 2: Beamer Presentation Audit

User: "Review my presentation slides for LaTeX issues"

Process:
1. Read slides.tex
2. Detect class: beamer
3. Run all standard checks
4. ADDITIONALLY run Beamer-specific checks:
   - Aspect ratio
   - Overlay density
   - Contrast estimation
   - Frame content balance
5. Generate audit report with Beamer section
6. Provide beamer_16_9_overlays.tex as reference
7. Highlight WCAG contrast requirements

Pattern 3: TikZ-Heavy Document Audit

User: "My document with lots of TikZ figures compiles very slowly"

Process:
1. Read document.tex
2. Count tikzpicture environments
3. IF count > 15:
   - STRONGLY recommend externalization
   - Generate externalization setup guide
   - Provide tikz_externalization.tex MWE
   - Explain shell-escape security
   - Show Makefile integration
4. Estimate compilation time savings

Pattern 4: Bibliography Migration

User: "How do I modernize my bibliography setup?"

Process:
1. Detect legacy BibTeX usage:
   - \bibliographystyle{}
   - \bibliography{}
2. Recommend migration to biblatex + biber
3. Provide modern_bibliography.tex as guide
4. Show step-by-step migration:
   - Remove old commands
   - Add biblatex package
   - Change compilation workflow
5. Explain benefits:
   - UTF-8 support
   - Flexible formatting
   - Better sorting

False Positive Mitigation

Conference Templates

IF document uses conference class (IEEEtran, ACM, etc.):
  SUPPRESS warnings about:
    - Package loading order (template may have specific requirements)
    - Class options (conference-mandated)
    - Bibliography style (often required by venue)

  STILL CHECK:
    - Compilation issues
    - TikZ externalization opportunities
    - Code quality (ChkTeX, indentation)

Legacy Documents

IF document appears to be legacy (pre-2010 packages):
  NOTE: Document may be intentionally using older packages
  DISTINGUISH:
    - Critical issues (will cause errors)
    - Modernization opportunities (optional improvements)
  PROVIDE migration path but acknowledge may not be desired

Minimal Documents

IF document is very short (<100 lines, simple structure):
  REDUCE recommendations to essentials
  DON'T recommend:
    - microtype (minimal benefit)
    - Complex cross-reference systems
    - Externalization (overhead not worth it)

Integration Points

With tex-runner Skill (if available)

IF tex-runner skill available:
  INVOKE for compilation test:
    tex-runner.compile(
      path=document.tex,
      engine=detected_engine,
      shell_escape=externalization_detected,
      timeout=300
    )

  PARSE results:
    - Errors → add to findings with severity=error
    - Warnings → add to findings with severity=warn
    - Success → note in report

With File Organization Skills

IF large project with multiple files:
  ANALYZE structure:
    - Main file
    - \input{} and \include{} files
    - figures/ directory
    - data/ directory for pgfplots

  RECOMMEND:
    - Organized directory structure
    - Separation of content and presentation
    - Version control (.gitignore for auxiliary files)

Output Format Standards

Audit Report Structure

1. Executive Summary (1 page)
2. Document Analysis (class, engine, packages)
3. Findings by Category (grouped, prioritized)
4. Detailed Findings (with evidence and references)
5. TikZ Analysis (if applicable)
6. Beamer Analysis (if applicable)
7. Compilation Guidance (commands, toolchain)
8. MWE References (links to examples)
9. Lint Configuration (ChkTeX, latexindent setup)
10. Action Items (prioritized checklist)

Fix Plan Structure

1. Overview (summary of fixes)
2. Priority 1 (critical errors)
3. Priority 2 (warnings)
4. Priority 3 (improvements)
5. Package Loading Order (complete preamble)
6. Specialized Fixes (TikZ, Beamer, bibliography)
7. Compilation Checklist (verification steps)
8. Testing (how to verify fixes)
9. Makefile (reproducible builds)
10. Resources (documentation links)

Performance Notes

• Fast checks (< 1 second): Document structure, package order, basic pattern matching
• Medium checks (1-5 seconds): Detailed preamble analysis, overlay counting
• Slow checks (5-30 seconds): Full compilation test (if invoked)

Prioritize fast checks; only invoke compilation test if:

1. User explicitly requests it
2. Static analysis reveals ambiguous issues
3. Document has known compilation problems

---

Version: 1.0.0 License: MIT Maintained by: Claude Skills Library