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

Mode	pipeline value	What it does	Workflow doc
Inline placement	inline	Places screened citations as inline \cite{} / \citet{} / \citep{} commands with a compiled references.bib. For economics, finance, and social-science journals (APA, MLA, Harvard, Chicago author-date, IEEE, Vancouver). .tex only.	references/phase-details-inline.md
Footnote placement	footnotes	Places screened citations as full formatted \footnote{} (LaTeX) or native OOXML footnotes (Word), with one-click legal/notes style selection (Bluebook, OSCOLA, Chicago notes-bib, APA 7th, McGill) and Id./supra short-form post-processing. .tex or .docx.	references/phase-details-footnotes.md
Restyle	restyle	Converts ALL existing footnote citations (hand-written or pipeline-placed) from one style to another. No spreadsheet required. .tex or .docx.	Restyle Pipeline section of references/phase-details-footnotes.md

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}

// 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 xelatex) or .docx (native OOXML footnotes via scripts/core/docx_support/); for .docx, skip every LaTeX-specific step (no xelatex, no %CITE-PLACED, no \bibliography{}).

• 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 6; then xelatex (one pass, no bibtex/biber).
• 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 xelatex twice to settle footnote numbers.

%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.

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.

Command	Purpose	Invocation
Launcher	Collect inputs, write run_config.json	python "[skill-dir]/scripts/launcher.py" (Bash timeout: 600000)
Ingest	.xlsx → citations.json + references_new.bib (deterministic)	python "[skill-dir]/scripts/core/ingest_citations.py" --input citations.xlsx --output-json citations.json --output-bib references_new.bib [--existing-bib references.bib] [--min-score N]
Verify (inline)	Audit existing \cite{} keys vs .bib + APIs	python "[skill-dir]/scripts/core/verify_citations.py" --mode inline --citations placement/existing_citations.json --bib references.bib --output placement/audit_report.json [--spreadsheet cites.xlsx]
Verify (footnotes)	Audit existing footnote citations vs APIs	python "[skill-dir]/scripts/core/verify_citations.py" --mode footnotes --footnotes placement/existing_footnotes.json --output placement/audit_report.json [--spreadsheet cites.xlsx]
Merge adjacent footnotes	Combine adjacent \footnote{}...\footnote{} (Phase 5 post-proc)	python "[skill-dir]/scripts/merge_adjacent_footnotes.py" --input OUT.tex --output OUT.tex --style <id> --skill-dir "[skill-dir]"
Short form	Style-aware Id./supra/ibid substitution (Phase 6)	python "[skill-dir]/scripts/short_form.py" --input OUT.tex --output OUT.tex --style <id> --skill-dir "[skill-dir]" [--plan-dir placement/]
Reorder cross-refs	Fix supra/Id. after manual footnote edits	python "[skill-dir]/scripts/reorder_crossrefs.py" --input OUT.tex [--plan-dir placement/]
Strip citations	Remove all %CITE-PLACED footnotes	python "[skill-dir]/scripts/strip_citations.py" input.tex [output.tex]
Migrate markers	Add %CITE-PLACED to legacy footnotes	python "[skill-dir]/scripts/migrate_markers.py" input.tex [output.tex]
Restyle (.docx)	Standalone restyle driver	python "[skill-dir]/scripts/docx_restyle.py" --config placement/run_config.json
Restyle (.tex)	Standalone restyle driver	python "[skill-dir]/scripts/tex_restyle.py" --config placement/run_config.json

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:

Aspect	Inline mode	Footnote mode
Citation command	\cite{key}, \citep{key}, \citet{key}	\footnote{Full formatted citation} (or OOXML footnote)
.bib file	Essential — compiled by LaTeX into the bibliography	Vestigial record only; not compiled
Compilation	pdflatex + bibtex/biber	xelatex only (footnotes are self-contained)
Citation styles	APA, MLA, Harvard, Chicago author-date, IEEE, Vancouver	Bluebook, OSCOLA, Chicago notes-bib, APA 7th, McGill
Short forms (Id./supra)	Not applicable — the bibliography style handles repeats	Phase 6 post-processing (short_form.py)
Phase count	5 phases (1–5)	6 phases (1–6)
Input format	.tex only	.tex or .docx

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