latex-template

name	latex-template
description	Use when you need to compare a project's LaTeX preamble against the working paper template.
allowed-tools	["Read","Glob","Grep","Edit","Write","Bash(ls*)","Bash(latexmk*)","Bash(lualatex*)","Bash(biber*)","AskUserQuestion","Skill"]
argument-hint	[project-path] [--apply]

Template Compliance

Compare a research project's LaTeX preamble against the working paper template (templates/latex-wp/your-template.sty + your-bib-template.sty). Classify every difference, produce a scored report, and optionally apply changes interactively.

When to Use

• After the template has been updated and you want to check older papers
• Before submission — verify the preamble is clean and up to date
• When a paper has mysterious compilation issues (often a stale preamble)
• During periodic maintenance or /system-audit
• When starting work on a paper that hasn't been touched in a while

When NOT to Use

• Setting up a new project — use /init-project-research instead (it copies the template)
• Fixing compilation errors — use /latex first, then run this
• Non-LaTeX projects — this skill is LaTeX-specific

---

Critical Rules

1. Never edit without --apply. Default mode is report-only. Without --apply, the skill produces a report and exits.
2. Never auto-apply Conflict items. Conflicts always require explicit user confirmation via AskUserQuestion.
3. Semantic comparison, not line-by-line. Compare packages, options, commands, and environments as logical units — not raw text diffs.
4. Preserve project-specific additions. Items classified as Keep are informational. Never suggest removing them unless they conflict with a template feature.
5. Template is the reference, not the authority. Projects may legitimately diverge. The skill reports differences — the user decides what to act on.
6. Compile after applying. If --apply makes any changes, always verify with /latex.

---

Protocol

Phase 1: Locate & Parse

1. Resolve the project path. Accept as argument or use CWD. Resolve to absolute path.

2. Find the project's preamble files. The canonical location is the Overleaf document, accessed via the paper/ symlink in the project directory. Search in this order:

   • New format (.sty files): paper/your-template.sty + paper/your-bib-template.sty (Overleaf symlink — preferred)
   • Legacy format: paper/settings.tex (Overleaf symlink)
   • If no paper/ symlink exists, check the project root for your-template.sty (or settings.tex)
   • Project root: your-template.sty + your-bib-template.sty or settings.tex (for local-only projects without Overleaf)
   • Any \input{settings} or \usepackage{your-template} in main.tex pointing elsewhere

   NEVER check settings/style files in subdirectories like docs/, to-sort/, docs/venues/, or any non-paper location. Only the main paper's preamble is relevant.

   If no preamble files are found, report error and exit.

3. Read the template. The canonical location is templates/latex-wp/ in Task Management:

   • $TASK_MGMT/templates/latex-wp/your-template.sty + your-bib-template.sty (canonical source)
   • Legacy fallback: settings.tex in the same location

   If no template files are found, report "Template not found — cannot compare. Verify that templates/latex-wp/ exists in Task Management." and exit.

4. Parse both files into semantic blocks:

   Block	What to extract
   Packages	Package name + options (e.g., [dvipsnames]{xcolor})
   Hyperref	All \hypersetup{} key-value pairs +

---

Phase 2: Compare

For each semantic block, compare the project against the template. Detailed check tables for each block: references/comparison-checklist.md

Blocks to compare: Packages (missing, extra, options, load order, duplicates) · Hyperref (missing keys, different values, urlstyle, cleveref ordering) · Bibliography (system mismatch, options, source mappings, field clearing, possessive citations) · Custom Commands (missing, different definitions, column types, math commands) · Theorem Environments (missing, different styles/counters, numberwithin) · Build Config (.latexmkrc existence, engine, output dir, PDF copy-back)

---

Phase 3: Classify

Label every difference with: Adopt (missing from project, safe to add) · Keep (project-specific, informational) · Conflict (needs human judgement, always ask) · Drop (redundant/superseded).

Full classification rules and when-to-use-each-label guidance: references/comparison-checklist.md

---

Phase 4: Check Auxiliaries

Check main.tex (preamble loading, documentclass, printbibliography, no stale bibliography commands) and .latexmkrc (exists, engine, output dir, PDF copy-back).

Full check tables: references/comparison-checklist.md

---

Phase 5: Report

Produce a structured compliance report. Full format: references/report-format.md

Quality Score

Apply numeric quality scoring using the shared framework: ../shared/quality-scoring.md

Start at 100 and deduct per issue:

Tier	Deduction	Examples
Critical	-15 to -25	Missing .latexmkrc, natbib vs biblatex conflict, missing hyperref, hyperref/cleveref load order wrong
Major	-5 to -14	Missing common packages (booktabs, microtype, enumitem), missing dvipsnames, duplicate package loads, missing custom commands (\todo, \red, \blue), missing source mappings, missing field clearing, missing cleveref
Minor	-1 to -4	Missing optional packages, different hyperref colours, missing theorem environments, missing math operators, missing \numberwithin

Verdicts

Score	Verdict	Meaning
95-100	Ship	Fully aligned with template
90-94	Ship with notes	Minor gaps, acceptable to proceed
80-89	Revise	Meaningful gaps — fix before submission
60-79	Revise (major)	Significant drift — several features missing
0-59	Blocked	Major conflicts or missing infrastructure — consider full resync

Report Sections

1. Header: Project name, path, score, date
2. Summary table: Counts by classification (Adopt / Keep / Conflict / Drop)
3. Per-item detail: Grouped by semantic block, showing classification + what/why
4. Auxiliaries: main.tex and .latexmkrc checks
5. Recommendations: Prioritised list of suggested actions

If --apply is not set, end with:

Run `/latex-template <path> --apply` to interactively apply changes.

---

Phase 6: Apply (--apply mode only)

Apply changes in dependency order to avoid compilation breakage:

1. Package options (e.g., add dvipsnames to xcolor)
2. Missing packages (insert in correct position relative to existing packages)
3. Hyperref configuration (update \hypersetup{} block)
4. Bibliography changes (only if user approves — always AskUserQuestion for system changes)
5. Custom commands (append after existing commands section)
6. Theorem environments (append after existing theorem section)
7. .latexmkrc (create or update)
8. Cleanup (remove duplicates, drop redundancies)

Apply Rules

• Show a summary first. Before making any edits, present the full list of changes to be applied (Adopt + Drop items) and ask for confirmation.
• Conflicts are always individual. Each Conflict item gets its own AskUserQuestion with the template version, project version, and context.
• Keep items are never touched. They appear in the report but are skipped during apply.
• Preserve comments and whitespace. When inserting packages, match the project's existing formatting style (e.g., if packages are grouped with comment headers, add to the right group).
• Log what was changed. After applying, list every edit made.

---

Phase 7: Verify (--apply mode only)

After applying changes:

1. Compile with /latex. This handles any secondary issues the changes might introduce.
2. Report the result:
   • If compilation succeeds: report success + number of changes applied
   • If compilation fails: report the error, suggest reverting specific changes, and note which change likely caused the issue

---

What This Skill Does NOT Do

• Does not rewrite main.tex structure. Only checks \input{settings} and bibliography commands.
• Does not check content quality. Use /proofread for that.
• Does not manage .bib files. Use /bib-validate for bibliography key issues.
• Does not handle journal-specific formatting. Use /retarget-journal for that.
• Does not compare across projects. Checks one project at a time against the template.

---

Examples

Report only (default)

"/latex-template ~/papers/costly-voice"

Produces a compliance report without making any changes.

Apply mode

"/latex-template ~/papers/costly-voice --apply"

Produces the report, then interactively applies Adopt and Drop changes with user confirmation.

Current directory

"Check my template compliance"

Runs on the current working directory in report-only mode.

After template update

"I updated the template — check all my papers"

Run on each project individually. This skill checks one project at a time.

---

Cross-References

• templates/latex-wp/your-template.sty + your-bib-template.sty — the canonical template this skill compares against
• /latex — used in Phase 7 to verify compilation after applying changes
• /audit-project-research — complementary: checks directory structure, this checks LaTeX preamble
• /bib-validate — complementary: checks citation keys, this checks bibliography system config
• /init-project-research — creates projects from the template; this skill verifies ongoing compliance
• /retarget-journal — handles journal-specific formatting (different concern)