| name | openspecy-design-public-api |
| description | Review proposed or changing OpenSpecy public R functions before implementation. Use for new exports, builder functions, argument additions, default changes, helper extraction, monolithic workflows, or APIs adapted from one-off scripts. |
Design OpenSpecy Public APIs
Run this review before editing public function signatures.
Workflow
- Read the current function, nearby package patterns, calling tests, vignette
examples, and the source script being generalized.
- Write the primary user workflow in one short pipeline using
OpenSpecy
objects. Treat that pipeline as the default behavior.
- Classify every proposed argument:
- Required input: data the function cannot infer.
- Meaningful policy: a common choice with at least two credible uses.
- Advanced tuning: pass through
... when the underlying function
already owns the option.
- Derived state: infer it; do not expose an argument.
- Speculative: remove it until a demonstrated workflow needs it.
- Prefer input presence over paired booleans. For example, a non-
NULL
lookup should trigger its join without a separate join_lookup flag.
- Keep advanced operations composable as standalone functions. Add them to a
monolith only when they are integral to the standard workflow and have
conservative defaults.
- Keep a helper internal when it has one caller and no independent user value.
Export it when it is broadly reusable, has a stable contract, and can be
documented and tested independently.
- Reuse package primitives and
OpenSpecy structure. Do not add table-only
pathways when the feature exists to protect spectral/metadata alignment.
- Check names and descriptions for domain generality. Prefer material,
hierarchy, metadata, and spectra terminology over one dataset's taxonomy.
Approval Gate
Before implementation, confirm:
- Each public argument has a concrete current use case.
- Defaults reproduce the maintainer's standard workflow.
- Optional steps can be composed with base
|>.
... is used only for a clearly identified downstream function.- Return types and side effects are singular and predictable.
- The plan names compatibility, tests, docs, NEWS, and benchmark impact.
If any item is unclear, simplify the API before adding code.
