r-package-check

---
name: r-package-check
description: Run the full R package release gate — regenerate docs, run the test suite, run R CMD check --as-cran, and triage every ERROR / WARNING / NOTE against CRAN policy before a release or submission. Use when the user says "check my R package", "R CMD check", "is this package CRAN-ready", "run devtools::check", "prepare for CRAN submission", or points at a directory containing a DESCRIPTION file. Produces a check report + CRAN-submission checklist in `quality_reports/`.
argument-hint: "[path to package root, or blank to autodetect from DESCRIPTION]"
disable-model-invocation: true
allowed-tools: ["Read", "Grep", "Glob", "Bash", "Agent", "Task", "Monitor"]
effort: high
metadata:
  author: Claude Code Academic Workflow
  version: 1.0.0
---

# `/r-package-check` — R Package Release Gate

Run the document → test → check → triage pipeline that decides whether an R package is releasable, then review the source for the issues `R CMD check` cannot see.

**Input:** `$ARGUMENTS` — the package root (a directory containing `DESCRIPTION`). If blank, autodetect by searching upward/within the working directory for `DESCRIPTION`.

---

## Constraints

- **Follow [`.claude/rules/r-package-conventions.md`](../../rules/r-package-conventions.md)** — the CRAN-readiness bar (0 errors, 0 warnings, explained notes) is the gate.
- **Treat `man/` and `NAMESPACE` as generated** — regenerate with `devtools::document()`; never hand-edit them.
- **Run the `r-package-reviewer` agent** on the source before declaring the package releasable.
- **Do not bump the version or write to CRAN.** This skill *checks*; the human decides when to submit.

---

## Workflow Phases

### Phase 0: Pre-Flight Report

```markdown
## Pre-Flight Report — R Package Check

**Package:** [name + version from DESCRIPTION]
**Root:** [path]
**Exported functions:** [from NAMESPACE / `@export` count]
**Dependencies:** Imports [list] · Suggests [list] · Depends [list]
**Toolchain available:** devtools [✓/✗], roxygen2 [✓/✗], testthat [✓/✗], R CMD [✓/✗], covr [✓/✗]
**Plan:** document → test → check --as-cran → triage → review
```

Detect the toolchain with a quick probe; if `devtools`/`R CMD` is missing, stop and tell the user what to install.

```bash
Rscript -e 'cat("devtools:", requireNamespace("devtools", quietly=TRUE),
               "roxygen2:", requireNamespace("roxygen2", quietly=TRUE),
               "testthat:", requireNamespace("testthat", quietly=TRUE),
               "covr:", requireNamespace("covr", quietly=TRUE), "\n")'
```

### Phase 1: Document

Regenerate `man/` + `NAMESPACE` and detect drift (generated docs that were not committed):

```bash
Rscript -e 'devtools::document("[pkg]")'
git -C "[pkg]" status --short man/ NAMESPACE   # any diff = generated docs were stale
```

If `git status` shows changes, flag: the committed `man/`/`NAMESPACE` were out of sync with the roxygen blocks.

### Phase 2: Test

```bash
Rscript -e 'devtools::test("[pkg]")'
```

Report failures and (if `covr` is available, Phase 4) coverage of exported functions.

### Phase 3: Check (`--as-cran`)

Run the full check. **This is slow** (minutes) — background-launch and stream with the **Monitor tool** rather than blocking:

```bash
Rscript -e 'devtools::check("[pkg]", args = "--as-cran")'
# or: R CMD build [pkg] && R CMD check --as-cran [pkg]_*.tar.gz
```

Then **triage every result** into a table:

| Result | Tier | CRAN-policy meaning | Action |
|---|---|---|---|
| … | ERROR / WARNING / NOTE | … | fix / justify |

- **ERROR / WARNING** → must fix before submission.
- **NOTE** → fix if cheap; otherwise write the justification you'd put in `cran-comments.md` (e.g., "New submission", "Found the following (possibly) invalid URLs … the URL is correct and reachable").

### Phase 4: Coverage (optional)

```bash
Rscript -e 'covr::package_coverage("[pkg]")'
```

Report per-function coverage; flag exported functions with 0% coverage.

### Phase 5: Source Review

```
Delegate to the r-package-reviewer agent:
"Review the package source at [pkg]"
```

The agent is read-only and returns its report; save it to `quality_reports/[pkg]_package_review.md`. Address Critical (CRAN-policy violations) and High (check WARNINGs) findings.

### Phase 6: Release Gate + Report

Save a report to `quality_reports/[package]_package_check.md` and present a verdict:

```markdown
## Release Gate — [package] [version]
- R CMD check --as-cran: E errors, W warnings, N notes
- Tests: P passed, F failed
- Coverage: X% of exported functions
- r-package-reviewer: C critical, H high
- **Verdict:** RELEASABLE / FIX-FIRST / POLICY-VIOLATION

### CRAN-submission checklist
[ ] 0 errors, 0 warnings; each note justified in cran-comments.md
[ ] Version bumped + NEWS.md updated
[ ] devtools::check_win_devel() / R-hub on other platforms (note: run separately)
[ ] Reverse-dependency check if this is an update (revdepcheck)
```

---

## Important

- **`--as-cran` or it doesn't count.** A plain `R CMD check` misses the policy checks that actually gate submission.
- **Generated files are generated.** If docs drift, the fix is `devtools::document()`, not editing `.Rd`.
- **The gate is 0/0/explained.** 0 errors, 0 warnings, every remaining note justified — nothing less is "CRAN-ready."
- **This skill does not submit.** Cross-platform checks (win-devel, R-hub) and the actual `devtools::release()` are the maintainer's call.

## Long-running checks: use the Monitor tool

`R CMD check --as-cran` and `covr` can run for several minutes. Don't block on them, and don't poll with `sleep`: start the **Monitor tool** with a command that runs the check itself, tees the full output to a log, and prints only the lines you would act on, e.g. `Rscript -e 'devtools::check("[pkg]", args = "--as-cran")' 2>&1 | tee quality_reports/r-package-check.log | grep --line-buffered -E 'ERROR|WARNING|NOTE|Status:|[Ee]rror'`. The watch ends when the check exits; set `timeout_ms` above the default 5 minutes (max 3600000). The filter must match failure as well as success, because silence looks the same as "still running". If you only need one notice when the check finishes, run it with Bash `run_in_background: true` instead and read the log when the job reports its exit. Monitor has no job-id parameter, so it cannot attach to a job already running in the background; see [`data-analysis/SKILL.md`](../data-analysis/SKILL.md) for the log-and-tail variant.