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)

1. Read the knowledge base FIRST — notation registry, narrative arc, applications database
2. Every new symbol MUST be checked against the notation registry
3. Motivation before formalism — no exceptions
4. Worked example within 2 slides/pages of every definition
5. Max 2 colored boxes/callouts per slide or page
6. Transition slides at major conceptual pivots (for slide decks)
7. 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:

1. 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)
2. Detect document type from keywords + project context (see Format Detection above)
3. Auto-select template — no confirmation needed
4. 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
5. 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.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, < 3 series) / plotnine (faceted/grammar) / matplotlib+seaborn (statistical/complex) — generate SVG, embed; 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
  Simple data chart (< 3 series, < 20 pts)	Line/bar/scatter chart	cetz-plot (Typst native, qk-cycle)
  Statistical chart (violin, kde, heatmap)	Statistical plot	matplotlib+seaborn (use(), SVG)
  Faceted / grammar-of-graphics chart	Layered plot	plotnine (theme_qk(), SVG)
  Complex chart (4+ series, annotations)	Publication chart	matplotlib (full API, SVG)
  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)

1. Compile: typst compile FILE.typ (or format-appropriate command)
   • Hard gate: exit code must be 0
2. 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]
3. 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?
4. Structural query: typst query for heading count, figure count
5. If issues found → fix → re-compile → re-render → re-check
6. 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/plotnine for Typst charts)
• 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
[ ] 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?"