JAXSR Review Skill — Red-Team, Engineering & Pedagogical Review

Systematically review JAXSR code, documentation, guides, and notebooks for API correctness, engineering quality, and pedagogical clarity.

Skill Activation

Activate this skill when the user invokes

/jaxsr-review

Invocation Syntax

/jaxsr-review <TARGET>                          # all scopes on one file/dir
/jaxsr-review --scope api <TARGET>              # API correctness only
/jaxsr-review --scope engineering <TARGET>      # safety/robustness only
/jaxsr-review --scope pedagogy <TARGET>         # clarity/explanation only

TARGET

examples/

docs/

src/jaxsr/

Scope Mapping

api

engineering

pedagogy

When no

--scope

Phase 1: Parse Arguments

1. Extract

   --scope

   value (default: all three scopes).
2. Extract

   TARGET

   path(s). Resolve globs. Verify files exist.
3. Classify each file by type:

   .ipynb

   (notebook),

   .md

   (guide/doc),

   .py

   (source/template).
4. Read each target file. For notebooks, examine every code cell.

Phase 2: API Correctness Review (scope =

api

)

This is the highest-priority review. Incorrect examples teach users wrong patterns.

API Truth Table

For every JAXSR API call found in the target files, verify against this authoritative reference. Each entry lists: function/class, correct usage, and common mistake.

Return Types

model.coefficient_intervals()

dict[str, (est, lo, hi, se)]

(lo, hi)

bootstrap_coefficients()

dict

"coefficients"

"mean"

"std"

"lower"

"upper"

"names"

result.intervals

result.names

result["names"]

bootstrap_predict()

dict

"y_pred"

"y_mean"

"y_std"

"lower"

"upper"

result.upper

result.lower

result["upper"]

conformal_predict_split()

dict

"y_pred"

"lower"

"upper"

"quantile"

y_pred, lo, hi = conformal_predict_split(...)

model.predict_conformal()

tuple

(y_pred, lower, upper)

cross_validate()

dict

"mean_test_score"

"std_test_score"

canonical_analysis()

CanonicalAnalysis

Class Attributes

BayesianModelAverage

.weights

dict[str, float]

.weights_

BayesianModelAverage

.expressions

list[str]

.models_

CanonicalAnalysis

.stationary_response

.predicted_response

CanonicalAnalysis

.stationary_point

.eigenvalues

.eigenvectors

.nature

.b_vector

.B_matrix

.warnings

AnovaResult

.rows

AnovaRow

AnovaRow

.source

.df

.sum_sq

.mean_sq

.f_value

.p_value

.p_value

None

Constructor Signatures

ActiveLearner(model, bounds, acquisition)

bounds

ActiveLearner(model, acq, bounds)

Composite(functions=[(w, acq), ...])

functions

(weight, AcquisitionFunction)

Composite([...], weights=[...])

ResponseSurface(n_factors=..., bounds=..., ...)

n_factors

n_factors

factorial_design(levels, n_factors, ...)

levels

factorial_design(n_factors=3)

levels

fractional_factorial_design(n_factors, resolution=3)

resolution

fraction=2

canonical_analysis(model, bounds=...)

bounds

factor_names=...

Sklearn Compatibility Protocol

model.get_params()

dict

model.get_params(deep=True)

estimator__param

MultiOutputSymbolicRegressor

model.set_params(key=val)

self

mo.set_params(estimator__max_terms=8)

mo.set_params(max_terms=8)

_clone_estimator(est)

type(est)(**est.get_params(deep=False))

n_jobs

n_jobs=1

n_jobs=-1

BasisLibrary

Method Names

ResponseSurface

.ccd()

.box_behnken()

.factorial()

.create_design()

Parameter Values

SymbolicRegressor(information_criterion=)

"aic"

"aicc"

"bic"

"cv"

compute_information_criterion(criterion=)

"aic"

"aicc"

"bic"

"hqc"

"mdl"

"hqc"

"mdl"

SymbolicRegressor

add_transcendental(funcs=)

["log", "exp", "sqrt", "inv"]

discrete_dims

dict[int, list]

list[int]

ANOVA Filtering

When iterating over

anova_result.rows

• MUST filter out rows with

  source

  in

  {"Model", "Residual", "Total"}

  — these are summary rows.
• MUST null-guard

  p_value

  — it is

  None

  for

  "Residual"

  and

  "Total"

  rows.
• Correct pattern:

  for row in result.rows:
      if row.source in {"Model", "Residual", "Total"}:
          continue  # skip summary rows
      pct = 100 * row.sum_sq / total_ss
  

Anti-False-Positive Rules

Do NOT flag these as errors:

• compute_information_criterion(..., criterion="hqc")

  — valid for standalone function

• model.predict_interval()

  returning a tuple — the method returns

  (y_pred, lower, upper)

• BayesianModelAverage.weights

  without underscore — this IS correct (no trailing

  _

  )
• Imports from

  jaxsr

  that exist in

  __all__

  — even if not commonly used
• Using

  .item()

  on JAX arrays outside JIT — this is fine outside JIT

Procedure

For each target file:

1. Extract all JAXSR API calls — imports, function calls, class instantiations, attribute access.
2. Check each call against the truth table above. Flag mismatches as CRITICAL.
3. Check imports — verify every imported symbol exists in

   jaxsr.__init__.__all__

   .
4. Check return type usage — if a function returns a dict and code unpacks as tuple, flag CRITICAL.
5. Check ANOVA loops — verify summary rows are filtered before computing percentages.
6. Copy-paste safety — verify each code block is self-contained OR explicitly references prerequisites.
7. Cross-references — verify any

   "See guides/..."

   or

   "See templates/..."

   references point to files that exist.

Phase 3: Software Engineering Review (scope =

engineering

)

Numerical Hazards

Check for:

• jnp.linalg.inv()

  on potentially singular matrices → suggest

  lstsq

  ,

  pinv

  , or SVD

• jnp.log(x)

  without guarding

  x > 0

  → suggest

  jnp.log(jnp.clip(x, 1e-30))

• Division by zero without guards
• Empty array operations (

  mean

  of empty, indexing empty)

• float()

  or

  int()

  on JAX tracers inside

  @jit

  -decorated functions
• Python

  if/else

  on runtime values inside

  @jit

  → suggest

  jax.lax.cond

  or

  jnp.where

Destructive Operations

Check for:

• shutil.rmtree()

  without path validation against deny-list (

  /

  ,

  /home

  ,

  /usr

  ,

  /etc

  ,

  /var

  ,

  /tmp

  ,

  $HOME

  )

• os.remove()

  or

  os.unlink()

  without existence check
• File overwrites without backup or confirmation

• subprocess

  calls with unsanitized inputs

Packaging & Sync

Check for:

• Symbols in

  __all__

  that are not imported in

  __init__.py

• Imports in

  __init__.py

  that are not in

  __all__

• Duplicate file inclusions in

  pyproject.toml

  (

  packages

  vs

  force-include

  )

• .claude/skills/jaxsr/

  and

  src/jaxsr/skill/

  out of sync

Dead Code

Check for:

• Unused imports (F401)
• Unused variables (F841)
• Bare expressions with no side effects (

  len(x)

  ,

  list(x)

  without assignment)
• Functions not exported and not called

Docstring Quality (for .py files)

Check that public functions have:

• Numpy-style docstring with Parameters, Returns, Raises sections
• Type annotations on all parameters and return type
• Docstring examples using actual function signatures (not stale names)

Notebook-Specific Checks

For

.ipynb

• Guard against negative values in physical simulations
• Use

  scipy.special.erfinv

  not

  np.math.erfinv

• Add null-guards for ANOVA

  p_value

• Check for cross-cell variable dependencies that break when cells run out of order
• Check for temp files that should be cleaned up

Phase 4: Pedagogical Review (scope =

pedagogy

)

Read the target as a first-time user and evaluate:

Structure & Flow

• Is there a logical progression from simple to advanced?
• Are concepts introduced before they're used?
• Does the material start with a motivating example or question?

Terminology

• Are domain-specific terms explained on first use?
  • Examples: "profile likelihood", "Pareto front", "AICc correction", "conformal prediction", "canonical analysis", "stationary point"
• Is terminology consistent within the document?
  • Check: "information criterion" vs "IC" vs "selection criterion"
  • Check: "basis functions" vs "candidate terms" vs "features"
  • Check: "selection strategy" vs "search strategy" vs "algorithm"

Explanation Quality

• Are the "why" questions answered, not just the "how"?
  • Example: Why AICc over BIC? When would you choose one over the other?
• Are decision points clearly marked with guidance?
• Are warnings and caveats placed before the code they apply to, not after?

Code Block Self-Sufficiency

Every code block must either:

1. Be self-contained (includes all imports and data setup), or
2. Clearly state "Continuing from above..." with a reference to the prerequisite section

Common failures to flag:

• Missing

  import numpy as np

  or

  from jaxsr import ...

• Using variables defined in earlier code blocks without re-defining them
• Using

  model

  variable before the fitting code block

Coverage Gap Analysis

Check which JAXSR features are NOT covered by any guide, template, or notebook:

Currently covered:

• Basis library building, Model fitting & selection, Uncertainty quantification
• Constraints, DOE workflow, Active learning, RSM, Known-model fitting, CLI
• Scikit-learn integration (cross-validation, GridSearchCV, Pipeline, model comparison)

Known gaps (flag as INFO if relevant to the target):

• Metrics comparison guide (R^2 vs AIC vs cross-validation)
• Export & reporting guide (JSON, LaTeX, callable, Excel, Word)
• Categorical variables (indicators, interactions, encoding/decoding)
• SISSO / power-law / rational-form basis builders
• Model serialization round-trip
• BayesianModelAverage standalone workflow
• Conformal prediction standalone usage
• Multi-response / multi-objective workflows

Phase 5: Generate Report

Produce a structured markdown report with this exact format:

# Review Report

**Target:** <file or directory path>
**Scope:** <api | engineering | pedagogy | all>
**Files reviewed:** <count>

## Summary

| Severity | Count |
|----------|-------|
| CRITICAL | N     |
| WARNING  | N     |
| INFO     | N     |

## CRITICAL

### [C1] <short title>
- **File:** <path>, <location (line N or cell N, line N)>
- **Code:** `<offending code snippet>`
- **Problem:** <what is wrong>
- **Fix:** `<corrected code>`
- **Source:** <source file:line where the correct API is defined>

### [C2] ...

## WARNING

### [W1] <short title>
- **File:** <path>, <location>
- **Code:** `<relevant code>`
- **Problem:** <what could go wrong>
- **Suggestion:** <recommended change>

### [W2] ...

## INFO

### [I1] <short title>
- **File:** <path>, <location>
- **Note:** <observation or suggestion>

---
*Review generated by `/jaxsr-review` skill*

Severity Definitions

Classification Rules

• Wrong return type usage (dict vs tuple, wrong attribute) → CRITICAL
• Wrong parameter name or argument order → CRITICAL
• Wrong parameter value (e.g.,

  information_criterion="cv"

  ) → CRITICAL
• Missing ANOVA summary row filter → CRITICAL
• Import of non-existent symbol → CRITICAL
• Cross-reference to non-existent file → WARNING
• Missing null-guard for ANOVA

  p_value

  → WARNING

• jnp.linalg.inv()

  without singularity guard → WARNING
• Unexplained domain term → WARNING
• Missing imports in code block → WARNING
• Coverage gap relevant to the target → INFO
• Inconsistent terminology → INFO
• Style suggestion → INFO

Execution Notes

• Read each target file completely before analyzing. Do not guess at contents.
• For directories, recursively find all

  .py

  ,

  .md

  , and

  .ipynb

  files.
• For notebooks, parse all code cells and markdown cells separately.
• When checking imports, read

  src/jaxsr/__init__.py

  to get the current

  __all__

  list.
• When verifying cross-references, use Glob to check file existence.
• If no issues are found for a scope, state "No issues found" in that section.
• Always include the Summary table, even if all counts are 0.