Merge pull request #91 from d-morrison/add-reprexes-skill

Add the "reprexes" skill (.claude/skills/reprexes)

Author: d-morrison

.claude/skills/reprexes/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: reprexes
+description: >
+  Isolate a technical problem into a minimal reproducible example ("reprex")
+  and iterate fixes on that instead of inside the full application. Use when
+  debugging a bug whose cause isn't obvious after a first look, when a failure
+  only surfaces deep in a large pipeline / app / render, when the full-context
+  test loop is slow, or before filing an upstream issue. Invoke explicitly
+  with /reprexes.
+user-invocable: true
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+# reprexes
+
+When a technical problem is hard to pin down, **don't debug it in the full
+context of the motivating application.** Extract a minimal, self-contained
+reproduction of the phenomenon, iterate candidate fixes on *that* (a fast,
+clean loop), then port the working fix back to the real code.
+
+Reference: <https://r4ds.hadley.nz/workflow-help.html#making-a-reprex>.
+The payoff is real: often, the act of building a thorough reprex surfaces the
+cause on its own — the noise you strip away was hiding it.
+
+## When this fires
+
+- A bug whose cause isn't obvious after a first read of the code.
+- A failure that only shows up deep inside a large pipeline, app, or a full
+  `quarto render` — where each reproduction attempt is slow.
+- Iterating on a fix that's expensive to test in the full context.
+- Before asking a human for help or filing an upstream/package issue — a
+  reprex is what they'll ask for anyway.
+
+Don't bother for a one-line obvious fix, or a problem you can already see and
+test cheaply in place.
+
+## The two requirements
+
+A reprex is only useful if it is BOTH:
+
+1. **Reproducible** — it captures *everything* needed to trigger the
+   phenomenon: every `library()` call, and code that creates every object it
+   uses. Someone (or a fresh session) can run it cold and see the same thing.
+2. **Minimal** — everything unrelated to the phenomenon is stripped out:
+   small or built-in data instead of the real dataset, only the lines that
+   matter.
+
+The tension between these two is the whole game: include enough to reproduce,
+but nothing more.
+
+## Procedure
+
+1. **Hypothesize the minimal trigger.** What is the smallest combination of
+   data + operation you believe causes the phenomenon?
+2. **Create a standalone scratch file** outside the repo tree (e.g.
+   `/tmp/reprex.R`, or a tiny `/tmp/reprex.qmd` for a render bug; on a
+   non-Unix machine use `tempfile(fileext = ".R")` / `tempdir()` for a
+   portable path). Put in it, in order:
+   - the package loads (`library(...)`),
+   - the minimal data (see tactics below),
+   - the minimal code that triggers the phenomenon, with a comment marking
+     where it goes wrong.
+3. **Run it in a clean session** and confirm it reproduces. For R, run with
+   `Rscript /tmp/reprex.R` (a fresh process — no stale `globalenv()` state
+   masking or faking the bug). For a Quarto page, render just that file:
+   `quarto render /tmp/reprex.qmd --to html`, not the whole site.
+4. **Minimize.** Remove pieces until the phenomenon disappears — the last
+   removal that "fixes" it implicates that piece. (Or build up from nothing
+   until it appears.) Keep the data as small as it can be while still failing.
+5. **Iterate fixes on the reprex**, not the full app. This is the fast loop
+   the whole technique exists to create.
+6. **Port the fix back** to the real code and verify it there.
+7. **Clean up.** Delete the scratch file (it lives in `/tmp`, so it never
+   touches the repo). If the bug was subtle, consider promoting the reprex
+   into a real regression test (`testthat`) instead of discarding it.
+
+## Minimizing the data
+
+- Prefer a **built-in dataset** (`mtcars`, `mpg`) or a hand-built
+  tiny frame over the real data.
+- If you must use a slice of real data, serialize the minimal slice with
+  `dput()` so the reprex recreates it inline — no external file dependency.
+- Shrink to the fewest rows/columns that still show the phenomenon.
+
+## R / Quarto specifics
+
+- In R packages and Quarto projects, reprexes are usually short R snippets or
+  a single standalone `.qmd` page. Respect the repo's lint config if the
+  reprex code will be ported back.
+- The **`reprex` package** (tidyverse, <https://reprex.tidyverse.org/>)
+  formats a reprex for sharing: it runs your code in a clean, separate R
+  session (via `callr` since reprex 2.0) and emits code **plus actual
+  output**.
+  Copy the code and call `reprex::reprex()` (reads the clipboard by default),
+  or point it at a file with `reprex(input = "/tmp/reprex.R")` (or a
+  `tempfile(fileext = ".R")` path on non-Unix machines) — handy from a
+  non-interactive CLI session where there's no clipboard. Use it when the
+  output is destined for a PR comment or an upstream issue. Useful arguments:
+  - `venue =` — output format:
+    - `"gh"` — GitHub-flavored Markdown (default)
+    - `"so"` / `"ds"` — Stack Overflow / Discourse
+    - `"slack"` — Slack message
+    - `"r"` — runnable R script with commented output
+    - `"html"` — HTML
+    - `"rtf"` — rich text for presentations
+  - `session_info = TRUE` — append `sessionInfo()` / `sessioninfo::session_info()`,
+    so versions travel with the reprex (set this when the bug may be
+    version-dependent).
+  - `std_out_err = TRUE` — capture stdout/stderr too (e.g. `system()` /
+    subprocess or C-level output that doesn't come back as normal R results).
+  - `wd =` — set the working directory when the code needs one.
+  - Validation bonus: because `reprex()` runs in a fresh session, if it errors
+    on a missing object or package, your example wasn't actually
+    self-contained — fix that before sharing.
+
+  Companion helpers handle "wild-caught" reprexes (all exported in reprex
+  2.x): `reprex_clean()` (strip the `#>` output markers from a rendered/pasted
+  reprex, leaving runnable code), `reprex_rescue()` (recover code from
+  R-console output with `>`/`+` prompts), and `reprex_invert()` (the inverse
+  of `reprex()` — recover the input code from a rendered reprex).
+- When the bug might be **version-dependent**, capture `sessionInfo()` (or set
+  `session_info = TRUE` above) in the reprex so versions are part of the
+  record. If you suspect *stale* packages are the cause,
+  `tidyverse::tidyverse_update()` outside the reprex can rule that out — but it
+  updates packages, it doesn't
+  record versions, so don't put it in the reprex itself.
+- Build artifacts (`_site/`, `_freeze/`, `.quarto/`) are common confounders
+  for "it renders differently" bugs — a clean standalone render sidesteps
+  stale freeze caches.
+
+## Before declaring the reprex good
+
+- A fresh session runs it top-to-bottom and shows the phenomenon (and nothing
+  else breaks first).
+- It references no object, file, or option it didn't create itself.
+- It's as small as you can make it and still reproduce.
+
+## Don't
+
+- Don't paste the entire app/module — that's the opposite of a reprex.
+- Don't commit scratch reprex files; keep them in `/tmp` (or `tempdir()` on
+  non-Unix machines) or a gitignored scratch path.
+- Don't iterate fixes in the slow full-context loop once you have a reprex
+  that reproduces.