render-report - SKILL.md Agent Skill

name: render-report description: Render a Quarto report (Stata engine) to HTML / PDF / DOCX. Performs freshness check on included tables/figures, verifies the Stata Quarto engine, and validates numerical claims before rendering. disable-model-invocation: true argument-hint: "[reports/file.qmd]" allowed-tools: ["Bash", "Read", "Grep", "Glob", "Task"]

Render a Quarto + Stata Report

Render a .qmd report that uses the Stata Quarto engine (or pure-Markdown Stata code blocks). Pre-flight checks ensure the report is complete, fresh, and honest (no unverified numerical claims).

When to Use

After completing an analysis, to assemble the writeup
Before sharing with coauthors / advisors
Before a paper-submission deadline

Steps

1. Resolve the file

From $ARGUMENTS find the .qmd. If just a basename, search reports/. If empty, list reports/*.qmd and ask.

2. Pre-flight checks

a) Quarto + Stata engine available:

quarto check

Confirm "Stata: OK" (or equivalent). If missing, emit a clear setup instruction:

"Quarto's Stata engine is not installed. Install with: pip install nbstata (or pip install pystata), then re-run."

Do NOT attempt to render without the engine — it will fail confusingly.

b) No inline analysis — grep the .qmd for analysis commands inside Stata code chunks:

grep -n -E "regress|reghdfe|ivreg|areg|xtreg|csdid" reports/<file>.qmd

If found inside {stata} chunks → flag and refuse to render. Analysis lives in dofiles/, not in reports.

c) Freshness check for every included artifact (per single-source-of-truth):

For each output/tables/X or output/figures/X referenced in the .qmd
Find the producing do-file (grep for the path in dofiles/)
If do-file mtime > artifact mtime → STALE → re-run via /run-stata BEFORE rendering

d) Citation completeness:

Extract every @key from the .qmd
Confirm each appears in references.bib

e) Numerical-claim validation:

Identify text claims with numbers (regex on the Markdown narrative outside code chunks)
Delegate each to the log-validator agent against the relevant logs/*.log
If any claim is UNVERIFIED → refuse to render until either the do-file re-runs or the claim is removed

3. Render

quarto render reports/<file>.qmd

By default, produces HTML in docs/ (or report-local _files/). For PDF or DOCX, the .qmd needs the format block to declare them.

4. Post-render verification

Confirm output exists and is non-empty
Open the rendered HTML and confirm figures and tables display (read the rendered file's image references)
No "Could not render" placeholders

5. Report to user

Path of rendered output
Freshness verdict
Numerical-claim verdict (N verified, 0 unverified)
Citation completeness (N keys, 0 missing)
Next step (commit / share / revise)

Examples

/render-report reports/analysis_report.qmd → Full pre-flight + render.
/render-report analysis_report → resolves to reports/analysis_report.qmd.

Troubleshooting

"No engine for stata" — install nbstata or pystata; see Quarto Stata engine docs.
Render hangs — typically the Stata engine launching a long computation. Reports should NOT do analysis; refactor into dofiles/.
Broken figure path — the .qmd references output/figures/X.pdf but the file doesn't exist. Re-run the producing do-file.
Bibliography file not found — the _quarto.yml should point to bibliography: ../references.bib (relative from reports/).

Notes

Reports are output, not source. They should NOT contain analysis logic. If a result is ad-hoc, put it in a do-file first, then include from there.
Numerical-claim validation is a HARD GATE. If a claim cannot be verified, the report does not render. This is per log-verification-protocol.
Output goes to docs/ for GitHub Pages compatibility (set in _quarto.yml).