Review R Code
Run a code quality review on R scripts in the sewage project. Produces a report — does NOT edit source files.
Input: $ARGUMENTS — a .R filename, directory path, or all.
Project-Specific Conventions
Script Structure
Pipeline scripts (layers 01-06):
Header block (########) → roxygen description → initialise_environment() → setup_logging() → CONFIG list → functions → main() → conditional execution (sys.nframe() == 0)
Analysis scripts (09_analysis):
Numbered sections with # === separators, inline package loading, direct execution (no main() wrapper)
Required Conventions
- Paths:
here::here() — never relative paths or setwd()
- Data formats:
arrow (parquet) for intermediate/final; DuckDB for large joins
- Pipe: Native R pipe
|> (not %>%)
- Naming:
snake_case for functions/variables, UPPER_SNAKE_CASE for constants
- Econometrics:
fixest::feols() for regressions
- Tables:
modelsummary → LaTeX with tabularray format
- SE:
vcov = "hetero" for heteroskedasticity-robust
- Factors:
forcats::as_factor() / forcats::fct_drop()
Key Files
- Scripts:
scripts/R/01_data_ingestion/ through scripts/R/09_analysis/
- Utilities:
scripts/R/utils/
- Output:
output/{figures,tables,html_plots,regs,log}/
Workflow
Step 1: Identify Scripts
- If
$ARGUMENTS is a specific .R file: review that file
- If
$ARGUMENTS is a directory: review all .R files in that directory
- If
$ARGUMENTS is all: review all scripts in scripts/R/
- If no argument: ask which scripts to review
Step 2: Review Each Script (9 Categories)
Category 1: Script Structure
- Pipeline scripts: header block, roxygen,
initialise_environment(), CONFIG list, main(), conditional execution
- Analysis scripts: numbered sections with
# === separators
- Clear separation of concerns
Category 2: Console Hygiene
- No unnecessary
print() / cat() pollution
- Logging via
setup_logging() in pipeline scripts
- Clean output — only meaningful messages
Category 3: Reproducibility
set.seed() where randomness is involved
- All paths via
here::here() — no setwd(), no relative paths, no hardcoded absolute paths
- No hardcoded values that should be in CONFIG
Category 4: Function Design
- DRY — no duplicated code blocks
- Functions at appropriate abstraction level
- Shared utilities in
scripts/R/utils/ where reuse is needed
Category 5: Figure Quality
- Axis labels present and readable
- Appropriate dimensions (not too wide/narrow)
- Consistent theme across plots
- Alpha transparency for overlapping points
- Saved to
output/figures/ via here::here()
Category 6: Data Persistence
- Intermediate results saved as parquet (
arrow::write_parquet())
saveRDS() for R-specific objects
- No orphaned temporary files
Category 7: Comments
- Explain why, not what
- Section headers for navigation
- No commented-out dead code
Category 8: Error Handling
- Graceful failures with informative messages in pipeline scripts
- File existence checks before reading
- Data validation where appropriate
Category 9: Polish
- Consistent style (indentation, spacing)
- No dead code or unused imports
- Clean namespace —
library() calls at top
- Native pipe
|> (not magrittr %>%)
Step 3: Present Summary
## Code Review: [filename/directory]
**Date:** YYYY-MM-DD
**Scripts reviewed:** N
### Issues by Severity
| Script | Critical | Major | Minor |
|--------|----------|-------|-------|
| ... | ... | ... | ... |
### Top 3 Critical Issues
1. ...
2. ...
3. ...
### Conventions Compliance
- [ ] here::here() for all paths
- [ ] Native pipe |>
- [ ] arrow/parquet for data
- [ ] fixest for regressions
- [ ] modelsummary for tables
### Score: XX / 100
Save report to output/log/code_review_[target].md.
Step 4: IMPORTANT
Do NOT edit any source files. Only produce reports. Fixes are applied after user review.
Principles
- Report only, never edit. The reviewer is a critic, not a creator.
- Project conventions matter. Flag deviations from the conventions above, not personal preferences.
- Proportional severity. A missing
set.seed() is Major. A missing comment is Minor. Using setwd() is Critical.
- Language-specific. Check R idioms — vectorised operations over loops, tidyverse patterns, proper use of factors.
- Pipeline vs analysis distinction. Different structure expectations for pipeline scripts vs analysis scripts.
1---2name: review-r3description: R code review for the sewage project. Checks script structure, reproducibility, function design, figure quality, and professional polish against project conventions (here::here, arrow/parquet, fixest, modelsummary, native pipe). This skill should be used when asked to "review the code", "check my script", or "code review".4argument-hint: "[filename, directory, or 'all']"5allowed-tools: ["Read", "Grep", "Glob", "Write", "Agent"]6metadata:7 source: https://skillmd.com/skills/brycewang-stanford/review-r8---910# Review R Code1112Run a code quality review on R scripts in the sewage project. Produces a report — does NOT edit source files.1314**Input:** `$ARGUMENTS` — a `.R` filename, directory path, or `all`.1516---1718## Project-Specific Conventions1920### Script Structure2122**Pipeline scripts (layers 01-06):**23```24Header block (########) → roxygen description → initialise_environment() → setup_logging() → CONFIG list → functions → main() → conditional execution (sys.nframe() == 0)25```2627**Analysis scripts (09_analysis):**28```29Numbered sections with # === separators, inline package loading, direct execution (no main() wrapper)30```3132### Required Conventions33- **Paths:** `here::here()` — never relative paths or `setwd()`34- **Data formats:** `arrow` (parquet) for intermediate/final; DuckDB for large joins35- **Pipe:** Native R pipe `|>` (not `%>%`)36- **Naming:** `snake_case` for functions/variables, `UPPER_SNAKE_CASE` for constants37- **Econometrics:** `fixest::feols()` for regressions38- **Tables:** `modelsummary` → LaTeX with `tabularray` format39- **SE:** `vcov = "hetero"` for heteroskedasticity-robust40- **Factors:** `forcats::as_factor()` / `forcats::fct_drop()`4142### Key Files43- Scripts: `scripts/R/01_data_ingestion/` through `scripts/R/09_analysis/`44- Utilities: `scripts/R/utils/`45- Output: `output/{figures,tables,html_plots,regs,log}/`4647---4849## Workflow5051### Step 1: Identify Scripts5253- If `$ARGUMENTS` is a specific `.R` file: review that file54- If `$ARGUMENTS` is a directory: review all `.R` files in that directory55- If `$ARGUMENTS` is `all`: review all scripts in `scripts/R/`56- If no argument: ask which scripts to review5758### Step 2: Review Each Script (9 Categories)5960#### Category 1: Script Structure61- Pipeline scripts: header block, roxygen, `initialise_environment()`, `CONFIG` list, `main()`, conditional execution62- Analysis scripts: numbered sections with `# ===` separators63- Clear separation of concerns6465#### Category 2: Console Hygiene66- No unnecessary `print()` / `cat()` pollution67- Logging via `setup_logging()` in pipeline scripts68- Clean output — only meaningful messages6970#### Category 3: Reproducibility71- `set.seed()` where randomness is involved72- All paths via `here::here()` — no `setwd()`, no relative paths, no hardcoded absolute paths73- No hardcoded values that should be in CONFIG7475#### Category 4: Function Design76- DRY — no duplicated code blocks77- Functions at appropriate abstraction level78- Shared utilities in `scripts/R/utils/` where reuse is needed7980#### Category 5: Figure Quality81- Axis labels present and readable82- Appropriate dimensions (not too wide/narrow)83- Consistent theme across plots84- Alpha transparency for overlapping points85- Saved to `output/figures/` via `here::here()`8687#### Category 6: Data Persistence88- Intermediate results saved as parquet (`arrow::write_parquet()`)89- `saveRDS()` for R-specific objects90- No orphaned temporary files9192#### Category 7: Comments93- Explain *why*, not *what*94- Section headers for navigation95- No commented-out dead code9697#### Category 8: Error Handling98- Graceful failures with informative messages in pipeline scripts99- File existence checks before reading100- Data validation where appropriate101102#### Category 9: Polish103- Consistent style (indentation, spacing)104- No dead code or unused imports105- Clean namespace — `library()` calls at top106- Native pipe `|>` (not magrittr `%>%`)107108### Step 3: Present Summary109110```markdown111## Code Review: [filename/directory]112**Date:** YYYY-MM-DD113**Scripts reviewed:** N114115### Issues by Severity116| Script | Critical | Major | Minor |117|--------|----------|-------|-------|118| ... | ... | ... | ... |119120### Top 3 Critical Issues1211. ...1222. ...1233. ...124125### Conventions Compliance126- [ ] here::here() for all paths127- [ ] Native pipe |>128- [ ] arrow/parquet for data129- [ ] fixest for regressions130- [ ] modelsummary for tables131132### Score: XX / 100133```134135Save report to `output/log/code_review_[target].md`.136137### Step 4: IMPORTANT138139**Do NOT edit any source files.** Only produce reports. Fixes are applied after user review.140141---142143## Principles144145- **Report only, never edit.** The reviewer is a critic, not a creator.146- **Project conventions matter.** Flag deviations from the conventions above, not personal preferences.147- **Proportional severity.** A missing `set.seed()` is Major. A missing comment is Minor. Using `setwd()` is Critical.148- **Language-specific.** Check R idioms — vectorised operations over loops, tidyverse patterns, proper use of factors.149- **Pipeline vs analysis distinction.** Different structure expectations for pipeline scripts vs analysis scripts.