LaTeX Conventions

LaTeX Conventions

You are writing or editing LaTeX paper sources. This skill governs the mechanics of citations, references, equations, figures, and the [CITE: ...] / [CLAIM-NEEDS-EVIDENCE] / [NEEDS-AUTHOR-DECISION] markers. It does not govern voice, argument structure, or claim verification — those are owned by other skills (see §1 Scope).

Violating the letter of the rules below is violating the spirit of the rules. "I appended to master.bib because refs.bib looked empty and it didn't seem to matter" is a violation, not a contribution.

1. Scope

What this skill governs:

• Citation handling: .bibsources lookup chain, key naming, append-to-refs.bib rules, \cite{} / \citep{} / \citet{} discipline.
• Reference discipline: \ref{} and \label{} form (semantic, not numeric); \eqref{} for equations.
• Equation numbering: numbered vs unnumbered, equation vs equation* vs align.
• Figure placement: [htbp] is the only acceptable specifier.
• Markers: exact format for [CITE: ...], [CLAIM-NEEDS-EVIDENCE], [NEEDS-AUTHOR-DECISION: ...].

What is OUT of scope (governed elsewhere):

Concern	Skill
Voice, tone, forbidden LLM phrases, sentence/paragraph rules	academic-style
Claim ↔ evidence ↔ function argument structure	claim-evidence-chain
Web-search-as-leads vs citations; DOI/arXiv extraction procedure	repo-scanning-protocol §6 Web Search Discipline
Figure type selection (bar vs heatmap vs scatter)	figure-design-patterns
Line-edit allowed/forbidden categories; multi-pass polish procedure	prose-editing-discipline

If you find yourself making a voice change or a claim change while applying this skill, stop — that is a different skill's job. This skill is mechanics only.

2. .bibsources Lookup Chain

Before writing any \cite{key} command, run the lookup chain to find or produce a valid bib entry.

The paper directory has this layout (see plugin README for canonical reference):

papers/<slug>/
├── .bibsources         # one absolute path per line, pointing at user's master .bib files
├── refs.bib            # plugin-managed; this skill appends verified entries here
└── working/...         # drafts

The chain — exactly five steps, in order:

1. (this skill) Read papers/<slug>/.bibsources. For each path listed, open that master .bib file and look up the citation key (or, if you do not yet have a key, look up by author/year/title fragments). If the entry is found in any master .bib, use that key. Stop.

2. (this skill) If no master hit, open papers/<slug>/refs.bib and look up the key (or author/year/title fragments). If found, use that key. Stop.

3. (delegated to repo-scanning-protocol §6 Web Search Discipline) If still not found, search online and verify the entry has a DOI (10.xxxx/...) or arXiv ID (e.g., 2401.12345). The verification step is repo-scanning-protocol's job; this skill does not perform it. Read that section before invoking WebSearch/WebFetch.

4. (this skill) If verification succeeded: construct a key per §3 Citation Key Naming, run the collision check, then append the entry to papers/<slug>/refs.bib (never to a master listed in .bibsources). Use the new key in your \cite{}.

5. (both skills enforce) If verification failed (no DOI/arXiv extractable, or metadata didn't match): emit [CITE: <one-sentence description>] at the cite location, and report in chat that this citation could not be verified. Do NOT write a \cite{} command. Do NOT invent a key.

Hard rule: NEVER append to a master .bib file listed in .bibsources. The user's master is read-only from this plugin's perspective. The plugin's papers/<slug>/refs.bib is the only file this skill writes to. If .bibsources lists three master files, all three are read-only; the plugin still writes only to refs.bib.

If .bibsources is missing or empty, treat as if the master list is empty — go directly to step 2 (refs.bib), then step 3 (web search). Do NOT create a .bibsources and do NOT propose master .bib paths to the user; that is a structural choice.

3. Citation Key Naming

When you append a new entry to refs.bib, construct the key as lastnameYEARfirstword:

• lastname: first author's last name, lowercase, ASCII-folded (Müller → muller, O'Neill → oneill).
• YEAR: 4-digit publication year (2024, not '24).
• firstword: first content word of the title, lowercase, ASCII-folded, punctuation stripped. Skip the articles a, an, the if the title starts with one.

Examples:

Title (first author)	Key
"Transformer-based classification of biosynthetic gene clusters" (Liu, 2024)	liu2024transformer
"Out-of-distribution evaluation for protein language models" (Kim, 2023)	kim2023outofdistribution (hyphens stripped)
"The role of attention in protein folding" (Patel, 2024)	patel2024role (skip "The")
"antiSMASH 7.0: New and improved predictions" (Blin, 2023)	blin2023antismash (preserve casing-folded form of the technical term)

Collision check — required before insert

Before appending an entry to refs.bib, read all existing keys from:

• every master .bib file listed in .bibsources, AND
• the current refs.bib

Use a simple grep -E '^@[a-zA-Z]+\{' <file> scan to extract keys (or read the files and parse). If your candidate key already exists in either set, disambiguate by appending a lowercase letter suffix: liu2024transformer → liu2024transformerb → liu2024transformerc, etc. Use the first letter that produces no collision.

Never silently overwrite an existing key. Never produce two entries with the same key in refs.bib.

4. \cite{} Discipline

Use the natbib-style commands when the venue allows them (most CS / bio venues do). Three forms:

Form	When to use	Renders as
\citep{key}	parenthetical citation (the citation is grammatically a parenthetical aside)	"(Liu et al., 2024)"
\citet{key}	narrative citation (the author is the grammatical subject of the sentence)	"Liu et al. (2024) showed that..."
\cite{key}	venue style demands the plain command (no natbib available)	venue-defined

Pick by grammar, not by aesthetic. If the sentence reads "Recent work has explored X (... 2024).", use \citep. If it reads "Liu et al. (2024) explored X.", use \citet.

Multiple citations in one cite command: \citep{liu2024transformer, kim2023outofdistribution} — keys ordered alphabetically by key (not by year, not by author). This is purely a stylistic convention for diff-stability.

Order of operations — strict:

1. Run §2 .bibsources lookup chain.
2. If you have a verified key, write \citep{key} (or \citet{key}).
3. If you do NOT have a verified key, write [CITE: <description>] instead. Never invent a key.

Never write a \cite{key} command whose key does not have a corresponding @…{key, entry in master.bib ∪ refs.bib. If you are about to write a citation but the lookup chain has not yet completed, run the chain first; do not place a \cite{} and "come back to fix it later".

5. \ref{} and \label{} Discipline

Semantic labels only. Never numeric. The label is a stable identifier for a thing; the rendered number is LaTeX's job.

Conventional prefix scheme:

Object	Label form	Reference form
Section / subsection	\label{sec:method}, \label{sec:results}	\ref{sec:method} (or \Cref{sec:method} if cleveref is loaded)
Figure	\label{fig:roc-curve}, \label{fig:training-loss}	\ref{fig:roc-curve}
Table	\label{tab:main-results}, \label{tab:ablation}	\ref{tab:main-results}
Equation	\label{eq:cross-entropy}, \label{eq:loss}	\eqref{eq:cross-entropy} (NOT (\ref{eq:cross-entropy}))
Algorithm	\label{alg:training}	\ref{alg:training}
Appendix	\label{app:proof}	\ref{app:proof}

Hard rules:

• Never \label{1}, \label{2}, \label{fig1}, \label{section3}. Anything that would break under reordering is forbidden.
• Suffix is the semantic name of the thing, kebab-case or snake-case (pick one per project; do not mix).
• Place \label{} immediately after the \caption{} for figures and tables; immediately after \section{} / \subsection{} for sections; inside the equation environment after the math content for equations.

If you find yourself wanting to write \label{fig1} because "the figure is the first one and that's the easiest", stop — pick the figure's semantic name (fig:roc-curve) instead.

6. Equation Numbering

Number an equation only if you reference it elsewhere. Unreferenced numbered equations clutter the right margin and force renumbering on every edit.

Environment	Numbered?	When
equation	yes	the equation is referenced via \eqref{eq:...}
equation*	no	display equation that is NOT referenced (requires amsmath)
\[ ... \]	no	shorter unnumbered display form
align	yes (per line, unless \nonumber / \notag)	multi-line equations that need to align (=, \le, etc.)
align*	no	multi-line aligned equations not referenced
gather / gather*	yes / no	multi-line stacked equations (no alignment)

Reference form: always \eqref{eq:loss}, never (\ref{eq:loss}) with manual parens. \eqref produces the parens automatically and stays consistent if the document switches to a different equation-numbering scheme.

If you find yourself writing equation (\ref{eq:...}), the fix is to delete the manual equation word and the manual parens and use \eqref{eq:...} — which renders as "(3)" and reads naturally inline ("by \eqref{eq:loss}, the gradient is...").

align is for multi-line equations that align on a symbol. Do not use align for a single equation. Do not use align for a sequence of unrelated equations — use separate equation environments.

7. Figure Placement

Use [htbp]. Always.

Meaning: here, top, bottom, page — LaTeX tries each in order and picks the first that works for layout.

NEVER use [H] from the float package. [H] forces the figure exactly here, breaking page balance, often producing huge whitespace gaps, and forbidden by most venues' style guides.

Other variants are also forbidden in this plugin:

• [h] alone — too restrictive; if h fails, LaTeX gives up and pushes to end of document.
• [t] or [b] alone — restricts placement unnecessarily; [htbp] includes these.
• [!htbp] — the ! overrides spacing constraints; acceptable in tight cases but [htbp] is the default; do not reach for ! first.

If a figure is being pushed too far from its reference (e.g., page 3 reference, page 5 figure), the fix is content-level, not placement-level:

• Move surrounding text so the figure has earlier eligible placement.
• Split a long paragraph that is preventing top-of-page placement.
• Tune the figure's size (width=0.6\textwidth) so it fits an earlier slot.

Never reach for [H] to "fix" a placement issue. The fix is the surrounding content.

\begin{figure}[htbp]
  \centering
  \includegraphics[width=0.7\textwidth]{figures/roc-curve.pdf}
  \caption{ROC curves for the three classifiers across five seeds.}
  \label{fig:roc-curve}
\end{figure}

8. Markers

Three first-class markers. They are correct, complete, and shippable outputs. Fabrication is the failure mode, not these markers.

[CITE: <one-sentence description>]

For citations that cannot be verified to a DOI or arXiv ID. Inline in the prose at the cite location.

Recent work [CITE: a 2023-2024 survey of OOD evaluation for protein language models] has examined this gap.

When to use:

• The .bibsources chain reached step 5 (web search yielded no DOI/arXiv match).
• You are drafting before the citation is known and want a placeholder that grep finds later.
• The cite is from author memory ("I'm pretty sure I read a paper about this") — always a [CITE: ...] until verified.

The description should be specific enough to search for: "2024 paper on transformer-based protein language models" beats "a related work".

[CLAIM-NEEDS-EVIDENCE]

For empirical claims with no figure / table / equation / citation pointer. Inline at the end of the sentence.

Our model converges 3x faster than the baseline. [CLAIM-NEEDS-EVIDENCE]

When to use:

• A claim is made in prose but no Figure N / Table N / equation reference / citation backs it up.
• You are drafting and the supporting evidence has not yet been chosen.
• A reviewer would ask "where is this shown?" and the answer is "nowhere yet".

The marker is a flag for the author to either (a) point to evidence by editing in a \ref{fig:...} / \cite{...}, or (b) soften / remove the claim. The plugin's claim-evidence-chain skill governs the substantive choice; this skill governs the format of the marker.

[NEEDS-AUTHOR-DECISION: <quoted reviewer comment or unresolved structural question>]

For reviewer comments that require structural revision (not line-level edit), or for unresolved structural questions. Insert as a LaTeX comment (lines starting with %).

% [NEEDS-AUTHOR-DECISION: Reviewer R2 says "section 3 narrative is unclear"; this requires restructuring, not line edit.]

When to use:

• Reviewer comment maps to "reorganize", "rename section", "add new experiment", "change emphasis between claims".
• A load-bearing claim's evidence is missing and the fix is "add evidence or soften" — both author choices.
• Two paragraphs disagree about a fact and resolving the disagreement requires the author's call.

Place the marker at the location in the draft where the structural change would happen, not at the top of the file. Also record in the polish changelog as [DEFERRED] if you are working in prose-polisher mode (see prose-editing-discipline §5 / §7).

Format summary

Marker	Format	Placement
[CITE: <description>]	inline LaTeX text	at the cite location
[CLAIM-NEEDS-EVIDENCE]	inline LaTeX text	end of sentence
[NEEDS-AUTHOR-DECISION: <quote>]	LaTeX comment (%)	at the location of the change

These three are the only sanctioned markers. Do not invent variants ([TODO: ...], [FIXME: ...], [CHECK: ...]); they will not be picked up by downstream tooling.

9. Cross-References

• REQUIRED SUB-SKILL: Use repo-scanning-protocol §6 Web Search Discipline for the search-and-verify step in the .bibsources chain (step 3 — DOI/arXiv extraction). This skill does NOT do verification; it does lookup-and-write. Read that section before invoking WebSearch or WebFetch for a citation.
• OPTIONAL: Use academic-style if you are also editing prose around the citation; this skill is mechanics, not voice.
• OPTIONAL: Use claim-evidence-chain to decide whether a claim needs a citation in the first place; once that is decided, this skill governs how the citation is written.

10. What You Must NOT Do

• NEVER append to a master .bib file listed in .bibsources. The user's master is read-only. New entries go to papers/<slug>/refs.bib. No exceptions.
• NEVER invent a \cite{key} whose key has no corresponding bib entry. Use [CITE: <description>] instead until the entry is verified and appended.
• NEVER use \label{1}, \label{fig1}, or any non-semantic label. Semantic name in the suffix, prefix by object kind (sec:, fig:, tab:, eq:, alg:, app:).
• NEVER use figure placement [H] from the float package. [htbp] is the only acceptable specifier; content-level fixes for misplaced figures.
• NEVER pull a citation from a search snippet without DOI/arXiv extraction. A search snippet is a lead, not a citation. The verification step lives in repo-scanning-protocol §6.
• NEVER skip the lookup chain because "this paper is well-known" or "the key is obvious". The chain catches collisions, prevents fabrication, and keeps refs.bib consistent. Run it every time.
• NEVER produce two @…{key, entries with the same key across master.bib ∪ refs.bib. Run the collision check before every append.
• NEVER use (\ref{eq:...}) with manual parens. \eqref{eq:...} is the only correct equation reference form.

11. Red Flags — STOP if you catch yourself thinking any of these

These signals mean you are about to violate the skill. Stop, undo the drift, and re-read the relevant section.

• "I'll just add this to master.bib since refs.bib is empty." → STOP. The user's master is read-only regardless of refs.bib state. Append to refs.bib. (§2 hard rule)
• "I'm pretty sure this paper exists at this DOI." → STOP. Pretty-sure is not verified. Run the verification step (delegated to repo-scanning-protocol §6) or emit [CITE: ...]. (§2 step 3)
• "The label number doesn't matter, it's just internal." → STOP. Labels are stable identifiers; numeric labels break under reordering. Use semantic names. (§5)
• "I'll fix the figure placement with [H] so it stays put." → STOP. [H] is forbidden. Fix the surrounding content instead. (§7)
• "I can use [CITE: ...] later, for now I'll write the citation." → STOP. The citation either has a verified bib entry now, or it is [CITE: ...] now. There is no "I'll fix this later" middle state. (§4)
• "This key is obvious; I don't need to grep for collisions." → STOP. The grep is two seconds. Run it. (§3)
• "I'll just write (\ref{eq:loss}) because \eqref is fancy." → STOP. \eqref produces parens automatically and is the project convention. (§6)
• "The .bibsources file lists three masters; I'll just append to the smallest one to be safe." → STOP. ALL masters listed in .bibsources are read-only. Append to refs.bib. (§2 hard rule)
• "I'll mix \cite and \citep because the venue style isn't clear." → STOP. Pick one form per draft and apply consistently. If unclear, use \citep for parenthetical and \citet for narrative; do not mix \cite{} with the natbib forms. (§4)
• "I already wrote the \cite{key} and the key turned out to not exist; I'll just leave it and hope." → STOP. Either find/append the bib entry per §2 chain, or replace the \cite{key} with [CITE: <description>]. The compile-time undefined-reference warning is not a someone-else problem. (§4)

If you catch any of these, undo the offending action and re-read §2 (Lookup Chain) and §10 (What You Must NOT Do) before continuing.