Cite Placement

Citation Placement

Unified router for three citation workflows. A single Tkinter launcher collects inputs and writes run_config.json; the "pipeline" value selects one of three modes, each with its own detailed workflow document.

Modes and Routing

Read the relevant workflow document at the start of each phase.

Launcher-First Protocol

When the user triggers this skill:

1. Run the launcher with a 10-minute timeout (the user needs time to browse and configure), using the skill's known absolute directory as [skill-dir], not the current working directory:

   python "[skill-dir]/scripts/launcher.py"
   

   Call it via the Bash tool with timeout: 600000.
2. The unified GUI presents the file fields and options for all three modes and offers three run buttons — Inline Placement, Footnote Placement, and Restyle — plus a Utilities area (Strip All Citations; Regenerate / Reorder Cross-Refs, with or without an existing registry). On any run button the launcher validates inputs and writes placement/run_config.json in the output file's parent directory, then prints machine-readable status lines to stdout.
3. Parse the launcher's stdout:
   • LAUNCHER_STATUS: success — proceed. If missing or cancelled, stop.
   • LAUNCHER_CONFIG_PATH: <path> — the absolute path to run_config.json. Use this path for all subsequent phases. All paths inside the config are absolute; do not assume the config lives in the current working directory.
4. Read run_config.json and route on config["pipeline"]:
   • "inline" → run the inline placement pipeline (references/phase-details-inline.md).
   • "footnotes" → run the footnote placement pipeline (references/phase-details-footnotes.md).
   • "restyle" → run the restyle pipeline (Restyle Pipeline section of references/phase-details-footnotes.md).
5. Run the selected pipeline end-to-end without asking questions or waiting for confirmation between phases. The only pause is the Phase 4 human-in-the-loop gate in the two placement modes, and only when auto_approve is false.

run_config.json shapes

The config always lives at <output_parent>/placement/run_config.json. The "pipeline" key selects the shape:

// inline
{"pipeline": "inline", "input_format": "tex", "project_folder": "...",
 "input_tex": "...", "input_xlsx": "...", "output_tex": "...",
 "citation_style": "apa|mla|harvard|chicago_author_date|chicago_notes|ieee|vancouver",
 "replan": false, "auto_approve": false, "citation_mode": "selective|comprehensive",
 "insertion_style": "prose|simple", "verify_citations": false}

// footnotes
{"pipeline": "footnotes", "input_format": "tex|docx", "project_folder": "...",
 "input_tex": "...", "input_xlsx": "...", "output_tex": "...",
 "replan": false, "auto_approve": false,
 "citation_style": "bluebook|oscola|chicago|apa|mcgill",
 "citation_mode": "selective|comprehensive", "verify_citations": false,
 "pincites": false, "pdf_folder": null}

// restyle
{"pipeline": "restyle", "input_format": "tex|docx", "project_folder": "...",
 "input_tex": "...", "input_xlsx": null, "output_tex": "...",
 "current_style": "...", "target_style": "..."}

Citation slots (% CITE:)

Drafts from the writing-article-plans skill mark where citations belong with typed placeholder slots, and its assemble_manuscript.py normalizes footnote-wrapped slots before handoff. A slot is a % CITE: LaTeX comment carrying a typed hint (e.g. % CITE: meta-analysis on Y). Slots are a .tex convention only — footnotes-mode .docx input has no slot support.

Core rule (both placement modes). If the input manuscript contains % CITE: slots, every slot MUST end the run either filled or explicitly reported as unfilled with a reason. Silent slot survival is a pipeline failure. Slots are author-declared citation demands, so citation_mode: "selective" governs only free placements and never skips a slot.

Three slot forms reach this skill:

1. Bare comment — % CITE: <hint> on its own line or at the end of a line.
2. Footnote-wrapped, two-line (\footnote{% / % CITE: <hint> / }) — the normal post-assembly form (brace-safe).
3. Footnote-wrapped, one-line — \footnote{% CITE: <hint>}; compile-unsafe (the % comments out the closing brace). Recognize it and recommend running writing-article-plans' assemble_manuscript.py first.

% RESULT: slots belong to a different pipeline and MUST never be touched or removed. The contract lives in the phase docs: Phase 1 enumerates slots into citation_slots, Phase 3a fills each or defers it to unfilled_slots, Phase 4 reports the tally, and Phase 5 executes the replacements and runs a deterministic grep closure check. See references/phase-details-inline.md and references/phase-details-footnotes.md.

Inline Mode — Phase Overview (5 phases)

Detailed instructions: references/phase-details-inline.md.

• Phase 1 — Manuscript Mapping. Read the .tex; produce placement/section_map.md and placement/existing_citations.json. Detect the citation package (natbib → \citet/\citep; biblatex → \textcite/\parencite; else basic \cite) and the bibliography backend (bibtex/biber). Cached unless replan is true. Read-only.
• Phase 1.5 — Existing Citation Verification (optional). Gated on verify_citations. Flags dangling \cite{} keys, hallucinated .bib entries, and spreadsheet overlaps into placement/audit_report.json.
• Phase 2 — Citation Ingestion. scripts/core/ingest_citations.py turns the .xlsx into citations.json + references_new.bib. Deterministic, no LLM.
• Phase 3 — Placement Planning (3a → 3b → 3c). 3a assigns each citation to all supporting sections (multi-placement is normal); 3b spawns one general-purpose sub-agent per section to draft anchors and cite commands, keyed to insertion_style (prose default — Types 1/2/3 with sentence rewriting; simple — parenthetical-only, no rewriting); 3c consolidates into placement/placement_plan.md. Cached / incremental: with replan: false, only cite keys absent from the planned_keys header trigger new planning.
• Phase 4 — HITL Review. Always print the plan. Pause for corrections when auto_approve is false; otherwise continue immediately.
• Phase 5 — Execution. Copy the .tex to a versioned output, insert cites (parenthetical = insert after anchor; prose/textual = replace anchor), merge references_new.bib, ensure \bibliographystyle{}/\bibliography{} (or \addbibresource/\printbibliography for biblatex), then compile with pdflatex + bibtex/biber + two more pdflatex passes.

Footnote Mode — Phase Overview (6 phases)

Detailed instructions: references/phase-details-footnotes.md. Accepts .tex (LaTeX \footnote{}, compiled with the manuscript's own engine — see the Engine preservation rule below) or .docx (native OOXML footnotes via scripts/core/docx_support/); for .docx, skip every LaTeX-specific step (no LaTeX compile, no %CITE-PLACED, no \bibliography{}).

Engine preservation rule (2026-09-01). Never impose an engine on a manuscript: compile with the manuscript's own engine — run python "[skill-dir]/scripts/core/tex_engine.py" <main.tex> (author's build log, else preamble signals; libertine+[T1]{fontenc} = pdflatex, fontspec = xelatex). A wrong engine substitutes fonts SILENTLY (warnings, not errors) — compiling a libertine+T1 manuscript under xelatex rendered an entire article in Computer Modern while reporting success. After any compile, verify parity when the author's PDF exists: pdffonts families and page count must match it.

• Phase 1 — Manuscript Mapping. Produce placement/section_map.md and placement/existing_footnotes.json, classifying each footnote (article/book/working_paper/case/legislation/cross_reference/discursive/mixed). Cached unless replan.
• Phase 1.5 — Existing Citation Audit (optional). Gated on verify_citations; verification cascade (OpenAlex → CrossRef → Google Scholar) into placement/audit_report.json.
• Phase 2 — Citation Ingestion. scripts/core/ingest_citations.py → citations.json + references_new.bib. Deterministic.
• Phase 3 — Placement Planning (3a → 3b → 3c). Style-specific rules are read from references/styles/<citation_style>.md and injected into the 3b sub-agent prompts; every placement carries the full citation string (Phase 6 handles repeats). 3c merges same-anchor placements into single multi-citation footnotes. Cached / incremental on the planned_keys header.
• Phase 4 — HITL Review. Pause when auto_approve is false.
• Phase 5 — Execution. Copy the manuscript; insert each \footnote{ with an invisible %CITE-PLACED marker immediately after the opening brace; apply Phase 1.5 audit fixes; tag any pre-existing footnotes with %CITE-PLACED; run merge_adjacent_footnotes.py; then Phase 5.5 when pincites is set; then Phase 6; then one pass of the manuscript's own engine (no bibtex/biber; see the Engine preservation rule).
• Phase 5.5 — Pincites (optional, .tex, gated on pincites). Acquire full texts — articles via OA → LibKey → HeinOnline/EZproxy, books/chapters via pdf_folder/OA/publisher search, cases via generic web search (any jurisdiction, best-effort). SSRN is NEVER fetched by the scripted session (it bot-blocks; the author 2026-08-30) — SSRN PDFs come through the user's Claude-in-Chrome browser into pdf_folder; acquire marks such works unacquired naming that route — verify printed-page maps (folio anchors; star pagination or paragraph numbers for cases), locate verbatim supporting quotes via Opus subagents, (the ABSTRACT and the INTRODUCTION are banned as support — quotes come from where the body develops the point, and a claim only ever announced gets no pincite), derive pages mechanically, rewrite footnotes, write placement/pincite/pincite_report.md. See Phase 5.5 in references/phase-details-footnotes.md. Subagent cap: at most 8 concurrent agents for ANY fleet this skill spawns (locators included) — more risks account rate limits (the author, 2026-08-30); shard the work and queue the remainder instead.
• Phase 6 — Short-Form Post-Processing. short_form.py converts repeat citations to the style's short form (Id./ibid/supra/shortened title/author-date) and writes placement/footnote_registry.json for later cross-reference reordering. Runs automatically after Phase 5; compile twice with the manuscript's own engine to settle footnote numbers.

Pincite remediation loop (Phase 5.5, after any apply round)

Not-placed occurrences are TRIAGED, never hand-fixed ad hoc: every one lands in a bucket — wrong-version / verifier-false-negative / map-offset / metadata-bleed / no-folios / by-design — and every bucket has a standard fix (re-acquire + adopt; map_hints.json; works.json + repin; ledgered accept). Since 2026-09-02 the map builder self-diagnoses the common buckets — repository cover sheets are classified without hints, a preprint that contradicts the cite reports version_mismatch (acquire or re-cite), two folio series in one PDF ask for trailing_pages, and an article-number page slot is settled by evidence and rendered <number>, at <page>. Since 2026-09-03 a comment line that owns its line (the %CITE-PLACED marker, an author's own-line note) ends a citation part exactly as a ; does (where the text before it ends a sentence and the text after it opens a citation or sentence) — a discursive footnote's prose, marker and citation are no longer one refused span — and a re-collect carries located quotes across a citation that only narrowed (same occurrence, same family size, same context up to blanked comment lines, no % trailing live text in the footnote's region); after upgrading, RE-RUN COLLECT before apply, and read collect's own lines (re-keyed, refused, orphaned quotes). The formatter reads an institutional author in small caps before the title (report shape) and, for an article-numbered Bluebook work, an article designator in the journal slot ("art. 8, at 28"). Full playbook: "Post-apply triage and remediation loop" in references/pincite-pass-design.md. Generalization rule: per-manuscript DATA (hint values, ledger entries) stays in the run directory; every MECHANISM (subcommand, hint key, verifier relaxation) lands in skill code with a test — scratchpad one-offs for recurring steps are defects.

Standalone pincite mode (existing citations, no placement run)

Phase 5.5 has no dependency on the placement pipeline. Every pincite subcommand reads only placement/run_config.json (three keys: output_tex, citation_style, pdf_folder), placement/citations.json, and the manuscript itself — never %CITE-PLACED markers, a .bib, or any other placement artifact. To pincite a manuscript whose citations the author already wrote:

1. Copy the manuscript into a working folder (never edit the author's copy in place) and create placement/ beside it.
2. Build placement/citations.json — one record per cited WORK, harvested from the manuscript's own footnotes by a Phase-1-style mapping pass (the existing_footnotes.json extracted_* fields are the template): cite_key (stable slug), title, authors, year, journal, doi (empty when unknown); add publisher/booktitle/entry_type where they decide work type. Titles must be long enough to match safely — collect drops records under 15 normalized chars (8 for cases) with a per-key reason.
3. Write placement/run_config.json: {"pipeline": "footnotes", "output_tex": "<working copy>", "citation_style": "<id>", "pincites": true, "pdf_folder": null}.
4. Run the normal Phase 5.5 chain unchanged: collect -> acquire -> extract -> locator fan-out -> apply, plus repin and audit rounds as needed.
5. Skip Phase 6 — the author's own short forms stay untouched. Scope fact: collect targets only occurrences carrying a work's full title, so existing Id./supra/shortened-title footnotes never receive pincites; whatever pages they already carry are the author's.

%CITE-PLACED marker rule

Every \footnote{} in a .tex output carries %CITE-PLACED immediately after the opening brace (a LaTeX comment pdflatex ignores, so the PDF is unchanged). The marker lets strip_citations.py cleanly remove all pipeline footnotes for a clean re-run, and it is preserved through merge and short-form rewrites. Interior markers are part of the same convention: a multi-citation footnote carries one marker line above EACH placed citation (so merging N marked footnotes yields one footnote with N markers, the head marker guaranteed), and every rebuild (short-form, reorder, merge) preserves the marker multiset verbatim, each marker staying with the citation it heads (tests/test_format_preservation.py pins this).

Restyle Mode — Overview

Detailed instructions: Restyle Pipeline section of references/phase-details-footnotes.md. Converts every existing footnote citation from current_style to target_style, correcting Id./ibid/supra cross-references and symbol-footnote numbering. The .tex path spawns one sub-agent per section and finishes with merge_adjacent_footnotes.py + short_form.py; the .docx path extracts footnotes via scripts/core/docx_support/, restyles them, and writes back via replace_footnote_text. Standalone drivers: scripts/docx_restyle.py and scripts/tex_restyle.py (each takes --config placement/run_config.json). Case citations, legislation, and discursive footnotes pass through unchanged.

Utilities

The launcher's Utilities area (and the corresponding scripts) support maintenance outside a full run:

• Strip All Citations — strip_citations.py removes every %CITE-PLACED footnote, yielding a clean manuscript for a from-scratch re-run.
• Regenerate / Reorder Cross-Refs — reorder_crossrefs.py reverses all short forms to full citations and re-applies them with correct footnote numbering after manual footnotes shift the numbering. Uses placement/footnote_registry.json (created by Phase 6); when the registry is absent it reconstructs from the current full citations.
• Migrate markers — migrate_markers.py retroactively adds %CITE-PLACED to footnotes in manuscripts produced before the marker convention.

Commands

[skill-dir] is the absolute path to this skill's directory. All paths shown as placement/... are relative to the output file's parent directory.

The verification report schema is unchanged from the source pipelines: inline mode reports dangling references, per-.bib-entry verification, and spreadsheet overlaps; footnotes mode reports per-citation verification status, Bluebook format issues with corrected strings, and spreadsheet overlaps.

Inline vs. Footnote Mode

The two placement modes differ in output form, compilation, and style set:

Chicago notes-bib and legal styles belong to footnote mode; the inline mode's chicago_notes option warns and points to footnote mode instead.