/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 — 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
## 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.
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):
Rscript -e 'devtools::document("[pkg]")'
git -C "[pkg]" status --short man/ NAMESPACE
If git status shows changes, flag: the committed man//NAMESPACE were out of sync with the roxygen blocks.
Phase 2: Test
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:
Rscript -e 'devtools::check("[pkg]", args = "--as-cran")'
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)
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]"
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:
## 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. Background-launch via Bash with run_in_background: true, capture the bash_id, and use the Monitor tool to stream progress (e.g. the checking … lines or process exit) instead of polling. See data-analysis/SKILL.md for the pattern.
