writer-pdf-export

name	writer-pdf-export
description	When and how to render a promoted export to PDF via the export_pdf tool. Reads the writer's draft → export → PDF lifecycle and the operator-facing failure modes when the host is missing pandoc or tectonic.
agents	writer, cognitive

Purpose

The writer agent's export_pdf tool renders a promoted export from markdown to PDF. The PDF lands alongside the markdown at exports/<slug>.pdf. This skill teaches when to call it and what the failure modes look like.

The lifecycle

create_draft  →  update_draft (any number)  →  promote_draft
      ↓                                              ↓
exports/<slug>.md exists                exports/<slug>.md (Promoted)
      ↓
operator runs approve_export
      ↓
exports/<slug>.md (Approved, citeable)
      ↓
export_pdf  →  exports/<slug>.pdf

Two important properties of this chain:

• export_pdf works on promoted exports, not drafts. The tool reads exports/<slug>.md. If you're still iterating in drafts/<slug>.md, the call will return "no promoted export at …" — that's correct; a PDF is a delivery artefact, not a working surface.
• Re-running on the same slug overwrites the PDF. Useful when the operator has approved a revision and asked for an updated artefact. Don't call it speculatively — generation is 1–5 seconds for a real document.

When to call it

• The operator asks for a PDF, or for "the report" / "the deliverable" in a context where a markdown file isn't enough.
• An approved export needs to leave the system (email, hand-off, archive). PDF is the universal artefact format.
• The operator references downloading from the Documents tab — that's PDF-shaped affordance.

When NOT to call it:

• The operator just promoted a draft and hasn't approved it yet. They may still want to revise. Wait for approve_export (or ask if you're unsure).
• For internal sharing of a draft. Markdown is fine.
• After every update_draft "just in case." Wasteful.

Failure modes (and what they mean)

The tool surfaces specific operator-actionable errors. When they come back, summarise them in plain language for the operator — don't paste the raw tool output.

"tectonic is not installed"

The host is missing the PDF rendering engine. Pandoc shells out to tectonic to actually produce the PDF; without tectonic, pandoc errors before producing anything.

What to tell the operator: "I can't generate the PDF because the tectonic binary isn't installed on this host. The operator-manual install section has the curl line for Linux and brew install tectonic for macOS. After install, ask me again and the export will work."

"no promoted export at exports/…"

Either the slug is wrong, or the draft hasn't been promoted yet. Check list_documents to see what's actually in exports/ and confirm the slug matches.

"PDF generation failed (exit N): …"

Pandoc or tectonic ran but couldn't produce a PDF. Typical causes: markdown contains LaTeX-incompatible content (rare but possible — heavy emoji, exotic Unicode), or tectonic couldn't fetch a needed package on its first run.

What to tell the operator: report the exit code and the first line of stderr; suggest re-running once if it looks like a transient package fetch, or ask for help if it looks like content.

Worth knowing

• The tool runs synchronously. If the operator is waiting on the reply, expect a 1–5 second pause on most documents; 5–15 on the first run after install (tectonic fetches LaTeX packages on demand).
• The PDF is plain pandoc-LaTeX article style. No corporate letterhead, no styled headers. If the operator wants styling, that's a follow-up plan (templates).
• The web GUI's Documents tab will eventually surface a "Download PDF" button alongside approved exports; until then the operator reads the PDF straight from .springdrift/knowledge/exports/.

Related skills

• delegation-strategy — call the writer agent to draft and promote; call export_pdf directly from the cog loop after the export is approved (no need to re-delegate to the writer).
• personal-index — the writer's draft / export workflow as a whole.