Document Creation Workflow

One prompt → one publication-quality document. Internal quality loop runs automatically.

Format Selection

User specifies format explicitly → use that
User doesn't specify → detect from project context:
- Has Slides/ directory → Beamer LaTeX
- Has Source/ or mainly .typ files → Typst
- Has Quarto/ directory → Quarto
Default for new projects → Typst (preferred modern format)

Format Detection (for `.typ`)

Detect document type from user request keywords:

resume, CV → CV template
slides, presentation, lecture → touying slides (see typst/references/touying-guide.md)
essay, paper → essay template
guide, study guide, reference → study guide
report, business → business report
reference card, cheat sheet → dense reference layout

Constraints

All formats: verify every citation against the bibliography.

Teaching material (lectures, slides, study guides): first read the project's knowledge base in .claude/rules/ (notation registry, narrative arc) and check each new symbol against it; motivation before formalism; a worked example within 2 slides/pages of each definition; transition slides at major conceptual pivots.

WHEN TO PAUSE (the ONLY case)

Request is genuinely ambiguous AND no project context to disambiguate:

No sibling .typ files, no PDFs, no clear topic in the prompt
Example: user says "make something" with zero context

In this case: ONE AskUserQuestion (topic + type), then proceed autonomously.

For everything else — proceed without asking. Template auto-selection is correct 90%+ of the time; user can re-invoke with explicit overrides if wrong.

PIPELINE

Phase 0: Auto-Discover

Run these before drafting, without stopping to confirm:

Scan project for related materials
- Glob for *.pdf, *.md, *.typ, images/ in the project directory
- If PDFs found → check for .parsed.md next to each; read if exists
- If no .parsed.md → parse using PDF handling rules (background for large files)
Detect document type from keywords + project context (see Format Detection above)
Auto-select template — no confirmation needed
Style inheritance: if sibling .typ files exist in the project:
- Read first 30 lines of the most recent sibling
- Match fonts, colors, qk preset
- Only inherit from files that use @local/qk presets; ignore raw inline styles
Build context: materials found, template chosen, style detected

Phase 1: Draft (autonomous — full document at once)

For Typst Documents (.typ):

Always import @local/qk:2.2.0 and set smart defaults
Apply qk components per the typst skill's component auto-use table:
- Warning paragraph → #warning[...]
- Key takeaway → #keypoint[...]
- Actionable advice → #tip[...]
- Common mistake → #trap[...]
- Memory aid → #memorize[...]
Visuals: add them as content is drafted, routed per the typst skill's "Visual Tool Routing (compact)" section and its "Visual Auto-detection" table (single source; details in typst/references/tool-routing.md).
Always add alt: text on all images
Always #set figure(placement: auto)
Write COMPLETE .typ file — not batches
For large docs (>30 pages): write in sections but don't pause between them

For Beamer Slides (.tex):

Check notation, apply creation patterns
No \pause or overlay commands (check project rules)
Write complete slide deck at once

For Quarto Slides (.qmd):

Standard RevealJS YAML with theme, bibliography
Environment parity with CSS classes
Plotly for Python-generated plots

Phase 2: Verify + Auto-Fix (autonomous — max 3 rounds)

Compile: typst compile FILE.typ (or format-appropriate command)
- Hard gate: exit code must be 0
Render sample PNGs:
- Documents <=3 pages → all pages
- Documents >3 pages → page 1, middle page, last page
- Presentations <30 slides → all slides
- Presentations 30+ → first 3, middle 3, last 3
- Command: typst compile FILE.typ /tmp/create-preview-{0p}.png --pages [SAMPLE]
Visual inspection — Read each PNG and check:
- Content overflow / cut off?
- Blank half-pages?
- Font fallback squares (missing font)?
- Missing images / broken references?
- Cramped text / unbalanced layout?
Structural query: typst query for heading count, figure count
If issues found → fix → re-compile → re-render → re-check
Cap at 3 lightweight fix rounds

Phase 3: Present (final output to user)

Deliver a summary:

## Created: [filename]

| Metric | Value |
|--------|-------|
| Pages | [N] |
| Sections | [N] |
| Visuals | [N figures, N diagrams] |
| Compile | PASS |
| Visual check | PASS / [issues noted] |
| Template | [template used] |
| Style inherited from | [sibling file or "none"] |
| Materials discovered | [list or "none"] |

**What could break:** [list risks]

**Next steps:** `/doc-review` for deep audit · `/finish` for full pipeline · `/excellence` for milestone

Figures & Code

Python scripts for data-driven content (plotly for Quarto only; Typst charts use lilaq by default, matplotlib/plotnine only for kde, pair or faceted plots)
Diagrams: TikZ in Beamer source, fletcher/chronos/timeliney in Typst (NEVER Python), SVG for Quarto
Save outputs as .svg for Typst embedding (preferred), .png for raster, .parquet for data persistence

Post-Creation Checklist

[ ] Document compiles without errors
[ ] No overflow issues (verified via PNG)
[ ] All citations resolve
[ ] Every definition has motivation + worked example
[ ] 2-3 Socratic questions embedded (for slides)
[ ] Transition slides between sections (for slides)
[ ] Visual aids present where content benefits from them
[ ] New notation added to knowledge base

Format-Specific Notes

Typst Pedagogical Constraints (for slides)

Motivation before formalism
Worked example within 2 slides of definition
Fragment reveals with #pause (touying) — max 2-3 per slide
Speaker notes with #speaker-note[...] for presenter context
Use touying themes via qk-slides (see typst/references/touying-guide.md)

Beamer Pedagogical Constraints

Same as Typst but using LaTeX environments
No \pause or overlay commands

Devil's Advocate for Non-Slide Documents

For guides: "Is this section ordering optimal for the reader?"
For CVs: "Is this ATS-compatible? Is the hierarchy clear?"
For pitch decks: "Does the narrative build to a clear ask?"
For essays: "Is the argument structure compelling?"