# Qmd Runner > QMD Runner Debugging - Skill: `wolf5996/qmd-runner` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add wolf5996/qmd-runner` - Raw SKILL.md: https://api.skillmd.com/api/skills/wolf5996/qmd-runner/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: wolf5996 (https://skillmd.com/u/wolf5996) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/wolf5996/qmd-runner --- # QMD Runner Debugging ## Overview - **Problem**: `quarto render` aborts at the first chunk that errors, so a single broken cell hides every downstream failure. Iterating one error at a time on a 20-chunk analysis notebook is slow. - **Solution**: programmatically extract each `{r}` chunk into a sibling `.R` runner where every chunk is wrapped in `tryCatch`. Run the runner, get a single PASS / FAIL / SKIP table for every chunk in one pass, fix everything, repeat. - **Rule**: every fix lands in the **source `.qmd`**. The runner is regenerated from the qmd each iteration — never hand-edit the runner. - **End state**: when every chunk is PASS / SKIP, the corresponding `quarto render` will succeed too. Renders go from a debugging tool to a final-output tool. ## When to Use - A `quarto render` of an analysis notebook errors out and the message is hard to parse - Adopting an inherited pipeline that has not been re-rendered in months - Upgrading a key dependency (`Seurat`, `dplyr`, `msigdbr`, `biomaRt`, `clusterProfiler`) and a sweep of qmds needs revalidating - Many chunks share in-memory state (e.g. GSEA pipelines where `feature_loadings` flows through several PC chunks) and you want chunk-level isolation of failures - Multi-script pipelines where downstream notebooks read checkpoints from upstream notebooks (`creating-analysis-projects` `read → scripts → checkpoints → write` layout) and you want to validate the whole DAG ## When NOT to Use - Single-chunk qmds where the cost of building a runner exceeds the diagnostic gain — just `quarto render` directly - Render failures caused by YAML / front-matter errors (not chunk code) — those need a different fix - Producing the polished `.html` artefact — the runner does not invoke Quarto, so the html does not get rebuilt; finish with `quarto render` once chunks are green ## Workflow ### R0 — Wire up the generator (once per repo) - Place `runners/generate-runner.R` at the repo root and a matching `.gitignore` exclusion - The generator is the only thing that gets committed; per-script runner outputs stay gitignored `.gitignore` excerpt: ```gitignore # Per-chunk debug runners (auto-generated from qmds) !runners/ !runners/generate-runner.R mcf7/scripts/runners/ hcc1806/scripts/runners/ ``` ### R1 — Generate runners for every active qmd - Run `Rscript runners/generate-runner.R ` (or pass several) for every notebook to be debugged - Each emits `/runners/.R` - Skip notebooks that are not worth runner-debugging (e.g. credentials-only deployment scripts) ### R2 — Iterative debug loop For each runner, in dependency order (01 → 02 → 03 → ...): 1. `Rscript .R 2>&1 | tee .log` 2. Read the PASS / FAIL / SKIP table at the bottom 3. For each FAIL: a. Diagnose the underlying error from the runner's `Error:` line b. **Edit the source qmd** (not the runner) to fix the root cause c. `Rscript runners/generate-runner.R ` to regenerate d. Re-run, confirm the chunk now PASSes 4. Move to the next runner once every chunk in the current one is PASS or SKIP ### R3 — Commit the fixes - `git status` now shows only the `.qmd` edits from step R2 - Commit with a single conventional-commits message (e.g. `fix: address chunk-level errors surfaced by runners`), or split per-script if the diff is large - Runners stay untracked ### R4 — Final `quarto render` - Run `quarto render ` sequentially in dependency order to produce the polished html and repopulate `write/` + `checkpoints/` end-to-end - All chunks should pass since the runners already proved it; if any chunk does fail in the actual render, it is usually a render-time concern (e.g. knitr cache, fig device, working directory) — drop back into R2 for that script ### R5 — Report - Print a per-script PASS table - Verify checkpoints and figures landed where expected ## Anatomy of a Runner Generated runner preamble (every runner starts with this): ```r # Locate the project .Rprofile by walking up from getwd() until we find it, # then setwd(repo_root) BEFORE sourcing it so renv/activate.R picks the # correct project library path. Finally setwd() into the script's directory # so the qmd's relative paths (../checkpoints/, ../write/) resolve correctly. local({ cand <- normalizePath(getwd(), winslash = "/") for (i in 1:8) { if (file.exists(file.path(cand, ".Rprofile")) && file.exists(file.path(cand, "renv/activate.R"))) break parent <- dirname(cand) if (parent == cand) break cand <- parent } Sys.setenv(SMARTSEQ_REPO_ROOT = cand) prev_wd <- getwd() setwd(cand) source(".Rprofile", local = FALSE) setwd(prev_wd) }) setwd(file.path(Sys.getenv("SMARTSEQ_REPO_ROOT"), "/scripts")) # Chunk-level outcome accumulator. RUNNER_RESULTS <- list() run_chunk <- function(label, expr) { cat(sprintf("\n=== [%s] START: %s ===\n", format(Sys.time(), "%H:%M:%S"), label)) result <- tryCatch({ eval(expr, envir = .GlobalEnv) cat(sprintf("=== [%s] PASS: %s ===\n", format(Sys.time(), "%H:%M:%S"), label)) list(status = "PASS", error = NA_character_) }, error = function(e) { cat(sprintf("=== [%s] FAIL: %s ===\n", format(Sys.time(), "%H:%M:%S"), label)) cat(sprintf(" Error: %s\n", conditionMessage(e))) list(status = "FAIL", error = conditionMessage(e)) }) RUNNER_RESULTS[[label]] <<- result invisible(result) } skip_chunk <- function(label, reason = "marked eval: false in qmd") { cat(sprintf("\n=== [%s] SKIP: %s (%s) ===\n", format(Sys.time(), "%H:%M:%S"), label, reason)) RUNNER_RESULTS[[label]] <<- list(status = "SKIP", error = NA_character_) invisible(NULL) } ``` Each chunk in the runner becomes: ```r # ---- chunk: