Cgpt Quarto Debugger

CGPT Quarto Debugger

Use this skill for Quarto build failures caused by document source, project configuration, or scholarly apparatus. Keep it distinct from cgpt-quarto-render-windows, which handles Windows PATH, PATHEXT, spawned-shell, and stale-render environment hardening.

Triage Boundary

Use this skill when symptoms point to:

• YAML/front matter syntax, nesting, duplicate keys, or wrong format options.
• Citation failures: missing bibliography, bad .bib path, missing keys, malformed entries, or CSL path issues.
• Cross-reference failures: unresolved @fig-*, @tbl-*, @eq-*, @sec-*, duplicate labels, wrong prefixes, or rendered ???.
• Include/filter/project issues: missing _quarto.yml, _metadata.yml, _variables.yml, partials, Lua filters, custom templates, or extension paths.
• Pandoc, Typst, LaTeX, knitr, or Jupyter errors that trace back to source content or chunk code.

If cmd, quarto, R, Python, or output freshness fails only in Codex/PowerShell/scheduled tasks, switch to cgpt-quarto-render-windows.

Workflow

1. Capture the exact render command, target format, error text, and expected output path.
2. Read the relevant .qmd plus nearby config files: _quarto.yml, _metadata.yml, include files, bibliography files, CSL files, filters, and referenced assets.
3. Classify the failure before editing: YAML, citations, crossrefs, includes, filters/templates, engine/chunk, or target-format incompatibility.
4. Make the smallest source/config fix that explains the observed failure.
5. Re-render the requested target when feasible.
6. Hand the resulting artifact to cgpt-render-check for final output validation.

Fast Checks

YAML

• Front matter starts and ends with ---.
• Indentation uses spaces, not tabs.
• Format options are nested under the target format.
• Values with colons or special characters are quoted.
• Common keys are spelled correctly: bibliography, csl, crossref, number-sections, reference-doc, include-before-body, include-after-body.
• Project-level config does not conflict with document-level config.

Citations

• bibliography: exists when citations appear.
• Bibliography paths resolve relative to the rendering document or project.
• Citation keys in text match .bib entry keys exactly, including case.
• .bib entries have balanced braces and valid field syntax.
• CSL files exist and are appropriate for the target style.

Crossrefs

• Every @fig-*, @tbl-*, @eq-*, and @sec-* reference has exactly one matching label.
• Labels use the right prefix and include the leading # where Quarto expects it.
• Figure/table captions are present when the target format requires them for crossrefs.
• Labels are not duplicated across included files.
• Reference text does not mix underscores and hyphens by accident.

Includes, Assets, And Filters

• Include paths, image paths, reference docs, and templates exist.
• Paths with spaces are quoted in YAML.
• Lua filters and Quarto extensions are installed or vendored into the project.
• Format-specific raw blocks are guarded with Quarto conditional content when rendering to multiple targets.

Useful Commands

Run from the project directory when possible:

quarto render "path\to\file.qmd" --to html --log debug
quarto render "path\to\file.qmd" --to docx --log debug
quarto check

For source inventory, prefer rg:

rg "@(fig|tbl|eq|sec)-|#(fig|tbl|eq|sec)-" "path\to\project"
rg "@[A-Za-z0-9_:-]+" "path\to\file.qmd"
rg "bibliography:|csl:|include-|filters:|reference-doc:" "path\to\project"

Rules

• Do not rewrite manuscript prose while fixing build mechanics unless the prose contains the broken reference, citation, or include.
• Do not treat a successful exit code as final validation; inspect output and run cgpt-render-check.
• Do not make Windows environment fixes in this skill; route those to cgpt-quarto-render-windows.
• Report the root cause, changed files, render command, and remaining warnings.