/cite-placement

name: cite-placement
description: >-
  Place pre-screened literature citations into a LaTeX or Word manuscript, or restyle the
  citations already in one. Three modes: (1) inline placement — inline \cite{}/\citet{}/\citep{}
  with a compiled references.bib, for author-date journals (APA, MLA, Harvard, Chicago
  author-date, IEEE, Vancouver); (2) footnote placement — full formatted \footnote{} or OOXML
  footnotes for legal and notes styles (Bluebook, OSCOLA, Chicago, APA, McGill) with Id./supra
  short forms; (3) restyle — convert existing footnote citations from one style to another.
  This skill is manual-invoke ONLY — trigger ONLY when the user explicitly runs /cite-placement
  or explicitly names the "cite-placement" skill. Do NOT auto-trigger on general citation,
  footnote, or reference requests.
version: 1.0.0
metadata:
  author: Claude Code

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