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 (Non-Negotiable, All Formats)

Read the knowledge base FIRST — notation registry, narrative arc, applications database
Every new symbol MUST be checked against the notation registry
Motivation before formalism — no exceptions
Worked example within 2 slides/pages of every definition
Max 2 colored boxes/callouts per slide or page
Transition slides at major conceptual pivots (for slide decks)
All citations verified against the bibliography

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 (silent — no pause)

Run all of these silently before drafting:

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:1.0.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[...]

Visual auto-detection (proactive): as content is drafted, match patterns to the best tool. Route by content type: diagrams → native Typst (fletcher/chronos/timeliney/herodot, NEVER Python); charts → cetz-plot (simple) → lilaq (complex) → matplotlib (last resort); images → /image-search / /mindmap / gemini-generate-image MCP.

Content pattern	Visual	Tool
Comparison of 2+ items, attribute grids	Table or grid	Typst native
Callout boxes, styled layouts	`rect()`, `block()`	Typst native
Sequential process, decision logic	Flowchart / decision tree	`fletcher`
System architecture, ER diagrams	Block / entity diagram	`fletcher`
Hierarchy or taxonomy	Tree diagram	`fletcher` or `/mindmap`
Topic overview, concept map	Mind map	`/mindmap`
Request-response, API flows	Sequence diagram	`chronos`
Project schedule, phases	Gantt chart	`timeliney`
Historical events, evolution	Timeline	`herodot`
Data trend, distribution (< 3 series)	Line/area/scatter chart	`cetz-plot`
Complex chart (4+ series, annotations)	Publication chart	`lilaq`
Company logo, brand mark	Logo	`/image-search --logo`
Real-world photo	Photo	`/image-search`
Conceptual illustration, metaphor	AI-generated image	`gemini-generate-image` MCP

See typst/references/tool-routing.md for full details, examples, and fallback chains.

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:** `/review` for deep audit · `/finish` for full pipeline · `/excellence` for milestone

Figures & Code

Python scripts for data-driven content (plotly for Quarto only; matplotlib as last resort for Typst)
Diagrams: TikZ in Beamer source, fletcher/chronos/timeliney/lilaq in Typst (NEVER Python), SVG for Quarto
Save outputs as .png/.svg for Typst embedding, .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
[ ] Max 2 colored boxes/callouts per slide/page
[ ] 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
Max 2 boxes/slide
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?"

create-document