Script Review
Review a script for documentation quality, code standards, and reproducibility. Helps ensure code is ready for the methods section.
Usage
/review_script [path] /review_script scripts/preprocessing.py /review_script scripts/ # Review all scripts in directory
When to Use
-
After writing a new script
-
Before running /write_methods
-
When passive checks flag undocumented scripts
-
During code review or cleanup
Execution Steps
- Load Script(s)
Read the specified script or all scripts in directory.
- Documentation Checklist
For each script, check:
Documentation Review: [script_name.py]
Module-Level Documentation
- Has module docstring explaining purpose
- Lists author/date (optional but good)
- Describes inputs/outputs
- Notes dependencies
Function Documentation
| Function | Has Docstring | Args Documented | Returns Documented |
|---|---|---|---|
| func1 | ✓/✗ | ✓/✗ | ✓/✗ |
| func2 | ✓/✗ | ✓/✗ | ✓/✗ |
Inline Comments
- Complex logic is explained
- Magic numbers are explained
- Non-obvious decisions documented
Inline Comment Guidance: Explain WHY, Not WHAT
❌ BAD: States the obvious (what the code does)
x = x + 1 # Increment x by 1 data = data.dropna() # Drop NA values
✅ GOOD: Explains reasoning (why we're doing it)
x = x + 1 # Offset for 1-based indexing in output file data = data.dropna() # Required by downstream model; NAs cause silent failures
❌ BAD: Obvious from context
if threshold > 0.5: # Check if threshold is greater than 0.5
✅ GOOD: Explains the magic number
if threshold > 0.5: # Optimized cutoff from ROC analysis (see supplementary Fig S2)
- Code Quality Checks
Code Quality
Strengths:
- [What's done well]
Issues:
- 🔴 Critical: [Must fix]
- 🟡 Recommended: [Should fix]
- 🔵 Suggestion: [Nice to have]
Reproducibility
- Random seeds set (if applicable)
- Parameters configurable (not hardcoded)
- Dependencies importable
- Docstring Templates
If missing, suggest adding:
Python function:
def process_data(input_file: str, threshold: float = 0.5) -> pd.DataFrame: """ Process raw data file and apply quality filtering.
Reads the input file, removes low-quality samples, and applies
normalization. Used as first step in the analysis pipeline.
Args:
input_file: Path to raw data CSV file
threshold: Quality score cutoff (default: 0.5)
Returns:
DataFrame with processed samples, shape (n_samples, n_features)
Raises:
FileNotFoundError: If input_file doesn't exist
ValueError: If threshold not in [0, 1]
Example:
>>> df = process_data("data/raw/samples.csv", threshold=0.6)
>>> print(df.shape)
(150, 2000)
"""
Python module:
""" Preprocessing module for RNA-seq data.
This module handles quality filtering, normalization, and batch correction for raw count data. It is the first stage of the analysis pipeline.
Scripts: - preprocess.py: Main preprocessing logic
Usage: python preprocess.py --input data/raw/counts.csv --output data/processed/
Author: [Name] Date: [Date] """
R function:
#' Process raw data file and apply quality filtering #' #' Reads the input file, removes low-quality samples, and applies #' normalization. Used as first step in the analysis pipeline. #' #' @param input_file Path to raw data CSV file #' @param threshold Quality score cutoff (default: 0.5) #' @return DataFrame with processed samples #' @export #' @examples #' df <- process_data("data/raw/samples.csv", threshold = 0.6) process_data <- function(input_file, threshold = 0.5) {
Implementation
}
- Generate Review Report
Script Review: [script_name]
Summary
- Documentation: [Good/Needs work/Missing]
- Code quality: [Good/Needs work]
- Reproducibility: [Ready/Needs work]
Documentation Status
Module Docstring: [✓ Present / ✗ Missing]
[If missing, suggest content]
Functions
| Function | Docstring | Quality |
|---|---|---|
| main() | ✗ Missing | Add description of entry point |
| process() | ✓ Present | Good, but add example |
Issues Found
🔴 Critical (Must Fix)
- [Issue] - Line [N]
# Current [problematic code] # Suggested [improved code]
🟡 Recommended
- [Issue with suggestion]
🔵 Nice to Have
- [Optional improvement]
Methods Section Notes
When documenting this script in methods.md, include:
-
[Key algorithm/method used]
-
[Important parameters: X, Y, Z]
-
[Any assumptions made]
Quick Fixes
Copy-paste these improvements:
[Ready-to-use docstrings and comments]
6. Offer to Apply Fixes
Review complete. Would you like me to:
A) Add the suggested docstrings to [script_name] B) Review another script C) Update methods.md with this script's documentation D) Show me the full suggested improvements
Choice?
Quality Standards
Documentation Levels
| Level | Description | Minimum For |
|---|---|---|
| 1 - Minimal | Module docstring only | Personal scripts |
| 2 - Basic | + Function docstrings | Shared code |
| 3 - Complete | + Examples, types | Publication |
| 4 - Comprehensive | + Tests, edge cases | Package release |
Target for publication: Level 3
Reproducibility Checklist
## Reproducibility Review
- [ ] No hardcoded absolute paths
- [ ] All file paths use params.yaml or CLI args
- [ ] Random seeds set and documented
- [ ] Package versions in environment file
- [ ] No reliance on global state
- [ ] Outputs are deterministic
- [ ] Error messages are informative
Related Skills
- write-methods
- Document script in methods section
- next
- Get next suggestion
Notes
- Good documentation now saves hours later
- Write docstrings as if explaining to a colleague
- Comments explain WHY, code explains WHAT
- Update docs when code changes