section-writing-agent

# Section Writing Agent (Step 4)

Faithful implementation of the Section Writing Agent from PaperOrchestra
(Song et al., 2026, arXiv:2604.05018, §4 Step 4, App. F.1 pp. 47–49).

**Cost: ONE LLM call** (App. B: "Section Writing Agent (1 call): A single,
comprehensive multimodal call to draft and compile the complete LaTeX
manuscript"). Do NOT split this into per-section calls — the paper
explicitly designs it as one comprehensive call so the model can maintain
global coherence across sections.

## Inputs

- `workspace/outline.json` — the master plan
- `workspace/inputs/idea.md` — technical details
- `workspace/inputs/experimental_log.md` — raw data for tables and qualitative analysis
- `workspace/drafts/intro_relwork.tex` — the template **with Intro + Related
  Work already filled in by Step 3**. This is your starting point. The
  preamble, package list, style, and the two pre-filled sections must be
  preserved verbatim.
- `workspace/citation_pool.json` — the citation map (`{key, title, abstract}`
  for each verified paper)
- `workspace/refs.bib` — the BibTeX file
- `workspace/inputs/conference_guidelines.md` — formatting rules
- `workspace/figures/` — the actual PNG files from Step 2 (used as
  multimodal vision input!)
- `workspace/figures/captions.json` — caption text per figure_id
- `workspace/tex_profile.json` — TeX package availability flags (written by
  `check_tex_packages.py` at Step 0). **Read this before generating any
  LaTeX.** It tells you which packages are installed so you select the right
  cross-reference pattern, font packages, etc. before you write — not after
  you try to compile.

## Output

- `workspace/drafts/paper.tex` — the complete LaTeX paper, with all sections
  filled. The Step 5 Refinement Agent will iterate on this file.

## How to do it

### 0.5. Read tex_profile.json and select LaTeX patterns

Before composing the prompt, read `workspace/tex_profile.json` and apply
these rules to every LaTeX choice in the generated paper:

| Profile flag | True → use | False → use instead |
|---|---|---|
| `use_cleveref` | `\cref{fig:X}`, `\cref{tab:Y}` | `Figure~\ref{fig:X}`, `Table~\ref{tab:Y}` |
| `use_nicefrac` | `\nicefrac{a}{b}` | `$a/b$` |
| `use_microtype` | `\usepackage{microtype}` | omit the line |
| `use_t1_fontenc` | `\usepackage[T1]{fontenc}` | omit the line |

If `tex_profile.json` does not exist (old workspace), default to the safe
fallback column (no cleveref, no nicefrac, no microtype, no T1 fontenc).

### 1. Pre-extract metrics from the experimental log

Run the deterministic helper:

```bash
python skills/section-writing-agent/scripts/extract_metrics.py \
    --log workspace/inputs/experimental_log.md \
    --out workspace/metrics.json
```

This parses the `## 2. Raw Numeric Data` section's markdown tables into
structured JSON. The Section Writing Agent uses this to construct LaTeX
booktabs tables without re-deriving values from raw text. Read
`references/latex-table-patterns.md` for the booktabs conventions.

### 2. Compose the prompt and make ONE multimodal call

Load `references/prompt.md` (verbatim Section Writing Agent prompt from App.
F.1). Prepend the Anti-Leakage Prompt from
`../paper-orchestra/references/anti-leakage-prompt.md`.

The user message contains:

- `outline.json` — full content
- `idea.md` — full content
- `experimental_log.md` — full content (tables AND prose)
- `intro_relwork.tex` — full content (this becomes `template.tex` for the prompt)
- `citation_pool.json` — full content (becomes `citation_map.json`)
- `conference_guidelines.md` — full content
- `figures_list` — array of `{figure_id, filename, caption}` from
  `captions.json` and the file listing
- **The actual figure PNGs** as multimodal image inputs, so the model can
  visually inspect them and write accurate descriptions / refer to them
  correctly in the prose.

If your host LLM has no vision input, fall back to text-only mode: pass the
captions in `captions.json` as descriptions and tell the agent it cannot see
the images directly. Quality drops noticeably (the paper notes that visual
grounding measurably improves figure-text alignment), but the pipeline
still completes.

### 3. Save the output

The agent's response is wrapped in `\`\`\`latex ... \`\`\`` fences. Extract
the LaTeX code and save to `workspace/drafts/paper.tex`.

### 4. Run the deterministic gates

```bash
# Orphan citation gate: every \cite{KEY} must exist in refs.bib
python skills/section-writing-agent/scripts/orphan_cite_gate.py \
    workspace/drafts/paper.tex workspace/refs.bib

# Latex sanity: matched braces, matched begin/end, no unescaped specials
python skills/section-writing-agent/scripts/latex_sanity.py \
    workspace/drafts/paper.tex

# Anti-leakage post-check: no author names, emails, affiliations
python skills/paper-orchestra/scripts/anti_leakage_check.py \
    workspace/drafts/paper.tex
```

If any gate fails, **re-prompt the writing call** with the gate's error
report appended to the user message and ask the agent to fix the specific
issues. Do NOT try to fix the gate violations by hand — the model needs to
see its own mistakes.

## Critical rules from the prompt

These are excerpted from `references/prompt.md` (App. F.1, pp. 47-49). The
host agent MUST honor them on the writing call:

### Existing-content preservation

- DO NOT modify the text, style, or content of sections that are already
  filled in `intro_relwork.tex`. Preserve Intro + Related Work verbatim.
- Keep the preamble (packages, document class, style) **exactly** as is.
- Come up with a good title if one is missing. Fill author names if missing
  (but the Anti-Leakage Prompt says not to invent real ones — use a
  placeholder like "Anonymous Authors" for double-blind).

### Data and tables

- Build LaTeX tables for the experimental results.
- Extract numeric values directly from `experimental_log.md`. **Do not
  hallucinate numbers** — use the exact values in the log.
- Use the `booktabs` package format: `\toprule`, `\midrul