vldaft-model-development - SKILL.md Agent Skill

name: vldaft-model-development description: Use when turning a statistical survival-model prompt into vldaft package code, especially new AFT distributions, cure models, censoring or truncation behavior, parameter/link definitions, likelihood/score implementations, C/Rust backend changes, gamlss2 family support, simulation checks, backend parity tests, and model-facing documentation.

vldaft Model Development

Overview

Use this skill to convert a model idea into a validated vldaft implementation. Start by pinning down the statistical contract, then route the change through the R API, C and Rust back ends, tests, and docs as needed.

Required First Steps

Read inst/site/llms.txt before editing. Inspect git status --short and preserve unrelated local changes.

For model prompts, produce a short implementation plan before coding unless the user explicitly asks for analysis only. Include:

Target model and user-facing API.
Parameter blocks, links, constraints, and coefficient naming.
Supported censoring/truncation cases.
Required implementation surfaces: R only, C, Rust, cure evaluator, gamlss2, methods, docs, tests.
Validation strategy.

If the prompt leaves the likelihood, parameterization, or censoring semantics ambiguous, ask the smallest clarifying question before implementation.

Model Contract Checklist

Before touching compiled code, write down the contract in local notes or the turn summary:

Response scale: time scale, log-time scale, or mixture over a baseline.
Linear predictors: mu, sigma, nu/cure, theta polynomial terms, or new parameter blocks.
Links and bounds: identity, log, logit, fixed values, shape constraints.
Likelihood contributions for right, left, interval, and counting-process inputs when supported.
Left-truncation adjustment.
Prediction outputs and whether they use raw or internally centered covariates.
Log-likelihood scale and Jacobian convention.

Do not bury a new convention in code only; expose it in docs and tests.

Implementation Routing

Use these routing rules:

R formula/API changes: update R/vldaft.R, methods in R/methods.R, tests, roxygen/Rd, and README or vignette examples when user-facing.
Standard non-cure likelihood changes: update both src/loscreg8.c and src/rust/src/model.rs, plus the C/Rust wrappers if call arguments change.
.Call() contract changes: update src/vldaft_fit.c, src/init.c, src/rust/src/lib.rs, and the R call site together.
Cure-model changes: update the R wrapper and src/vldaft_cure_eval.c; add or adjust gamlss2 family behavior in R/family_aft.R when relevant.
New parameter blocks: update coefficient naming, summary/print methods, coef(), vcov(), predict(), and documentation.
Compile-time limits: keep C MAXCOV and Rust limits in sync.

Keep implementation/tests separate from documentation-only commits when the diff is large.

Numerical Validation

Prefer checks that prove the model, not just the plumbing:

Simulate data from the target model and verify recovery or likelihood improvement over a nested model.
Compare analytic scores with finite differences where practical.
For standard AFT back-end changes, test C/Rust parity to tight tolerance.
For gamlss2 support, compare log-likelihoods and linear predictors against standalone vldaft() on the same simulated data.
Exercise censoring cases touched by the change: right, left, interval, and left truncation as relevant.

Validation Ladder

Run the narrowest meaningful checks first, then broaden:

testthat::test_file("tests/testthat/test-vldaft-basic.R")
testthat::test_file("tests/testthat/test-vldaft-cure.R")
devtools::test()

For compiled or exported API changes, also run:

R CMD INSTALL .

For docs, vignettes, or pkgdown navigation changes, run:

pkgdown::build_site(devel = TRUE, preview = FALSE)

Report any skipped validation and why.