flonat/claude-research/latex-scaffold

LaTeX Scaffold

Convert an approved Markdown draft into a minimal, compilable LaTeX project. This is a deterministic format conversion — prose quality should already be addressed in the source draft.

When to Use

• Converting a literature review, survey, or report from Markdown to LaTeX for PDF output
• Turning meeting notes or drafts into a formatted document
• Bootstrapping a LaTeX project from an existing outline
• Any time you need md→tex without rewriting content

Inputs

• A Markdown file (.md) — the draft to convert
• A .bib file (optional) — if the draft contains citations

Outputs

• A .tex file ready to compile with latex
• The fail-closed canonical .latexmkrc if one does not already exist. Invoke the latex pre-flight to copy the canonical artifact; never synthesize selected directives.

Workflow

Step 1: Analyse the Draft

Read the Markdown file and inventory:

• Heading structure (determine \section / \subsection depth)
• Citations ([@Key] or [@Key1; @Key2] patterns)
• Tables (Markdown pipe tables)
• Math blocks ($...$ inline, $$...$$ display)
• Figures (![caption](path))
• Code blocks (fenced with language)
• Whether an abstract section exists

Step 2: Create the LaTeX File

Apply these conversion rules:

Preamble Template

\documentclass[a4paper,11pt]{article}
 
\usepackage[a4paper,margin=1in]{geometry}
\usepackage{hyperref}
\hypersetup{colorlinks=true,linkcolor=blue,citecolor=blue,urlcolor=blue}
\usepackage{booktabs}
\usepackage{tabularx}
\usepackage{graphicx}
\usepackage{amsmath,amssymb}
\usepackage{enumitem}
\usepackage[backend=biber,style=authoryear,natbib=true]{biblatex}
\addbibresource{references.bib}
 
\title{...}
\author{...}
\date{\today}
 
\begin{document}
\maketitle
% content here
\printbibliography
\end{document}

Adjust the preamble based on what the draft actually uses (e.g., skip graphicx if no figures). The natbib=true option provides \citet/\citep compatibility. If the project already uses natbib (e.g., with a journal .bst file), keep natbib — but for new scaffolds, biblatex is the default.

Step 3: Strip Markdown Residue

After conversion, scan the .tex file for any remaining Markdown syntax:

• ## heading markers
• ** bold markers
• [@ citation markers
• Pipe | table syntax
• ![ image markers

These indicate incomplete conversion — fix them.

Step 4: Wire Bibliography

• If a .bib file exists in the project, point \addbibresource{} to it
• If the project has a references.bib, use that
• If no .bib exists but citations are present, create placeholder comments: % TODO: create .bib with keys: Key1, Key2, ...
• Ensure \printbibliography is at the end of the document (not \bibliography{})

Step 5: Compile and Verify

Run latex to compile. Verify:

• [ ] Document compiles without errors
• [ ] All citations resolve (or are marked as TODO)
• [ ] Tables render correctly
• [ ] Math renders correctly
• [ ] Page count is reasonable

Rules

• No content rewriting — this is format conversion only. Do not improve prose, fix grammar, or reorganise sections.
• Preserve all content — every paragraph, figure reference, and citation in the draft must appear in the .tex output.
• Strip heading numbering — if the draft has numbered headings like 1.2 Methods, let LaTeX handle the numbering (just use \subsection{Methods}).
• Use `latex` for compilation — never bare pdflatex or latexmk without out/ directory.
• Bold caption lines like **Table 1. Description** immediately before a pipe table should become \caption{Description} inside a table float.

Cross-References

Citation Contract

<!-- paperpile-citation-contract -->

1. Paperpile is the only source of truth for committed citation keys and BibTeX metadata.
2. Before writing \cite{key}, verify with paperpile get-item key and paperpile export-bib key.
3. Resolve unknowns in order: DOI lookup → Paperpile substring search → refpile semantic search → Paperpile verify.
4. A DOI miss is not non-membership; continue with title/author search and refpile.
5. If unresolved, write \CiteTodo{slug}{title/author/year/DOI hint} — never a guessed key.
6. Drafting sub-agents must not write/edit the active .bib; only the orchestrator regenerates it from Paperpile exports.
7. Stage genuine new refs under .paperpile-import/ for manual Paperpile import; don't cite until Paperpile mints the key.
8. Run scripts/bib/citation_lint.py before commit; zero placeholders, zero non-Paperpile keys, zero hand-authored metadata.

See rules/paperpile-citations.md for the full workflow.